diff --git a/reference/7.6/Microsoft.PowerShell.Utility/New-Guid.md b/reference/7.6/Microsoft.PowerShell.Utility/New-Guid.md index 86803f9e45f..40794490dd1 100644 --- a/reference/7.6/Microsoft.PowerShell.Utility/New-Guid.md +++ b/reference/7.6/Microsoft.PowerShell.Utility/New-Guid.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 01/24/2024 +ms.date: 03/26/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/new-guid?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: New-Guid @@ -34,8 +34,14 @@ New-Guid [-InputObject ] [] ## DESCRIPTION -The `New-Guid` cmdlet creates a random globally unique identifier (GUID). If you need a unique ID in -a script, you can create a GUID, as needed. +The `New-Guid` cmdlet creates a Version 7 globally unique identifier (GUID). Version 7 UUIDs +contain a millisecond-precision timestamp and are sortable. If you need a unique ID in a script, +you can create a GUID, as needed. + +> [!NOTE] +> In PowerShell 7.5 and earlier, `New-Guid` created Version 4 (random) UUIDs. Starting in +> PowerShell 7.6, the default changed to Version 7. If you need a Version 4 UUID, use +> `[guid]::NewGuid()` directly. ## EXAMPLES @@ -45,7 +51,7 @@ a script, you can create a GUID, as needed. New-Guid ``` -This command creates a random GUID. Alternatively, you could store the output of this cmdlet in a +This command creates a GUID. Alternatively, you could store the output of this cmdlet in a variable to use elsewhere in a script. ### Example 2: Create an empty GUID @@ -95,6 +101,25 @@ Guid 01234567-89ab-cdef-0123-456789abcdef ``` +### Example 5: Create specific UUID versions using .NET APIs + +This example shows how to create specific UUID versions using .NET APIs directly. + +```powershell +[guid]::CreateVersion7() +[guid]::NewGuid() +``` + +```Output +Guid +---- +019588a4-dbe2-7f30-8b9f-4a1c0e5d3a28 +d61bbeca-0186-48fa-90e1-ff7aa5d33e2d +``` + +The version number appears in the third group of the GUID string. Version 7 UUIDs start with a +`7` in that position (`7f30`), while Version 4 UUIDs show a `4` (`48fa`). + ## PARAMETERS ### -Empty @@ -150,8 +175,15 @@ The cmdlet passes string input to the constructor of the **System.Guid** class. support strings in several formats. For more information, see [System.Guid(String)](/dotnet/api/system.guid.-ctor#system-guid-ctor(system-string)). -When used without string input or the **Empty** parameter, the cmdlet creates a Version 4 -Universally Unique Identifier (UUID). For more information, see -[System.Guid.NewGuid](xref:System.Guid.NewGuid). +When used without string input or the **Empty** parameter, the cmdlet creates a Version 7 +Universally Unique Identifier (UUID) as defined in +[RFC 9562](https://www.rfc-editor.org/rfc/rfc9562). + +In PowerShell 7.5 and earlier, the cmdlet created a Version 4 (random) UUID. If you need a +Version 4 UUID, use `[guid]::NewGuid()`. To explicitly create a Version 7 UUID, use +`[guid]::CreateVersion7()`. + +For more information, see +[System.Guid.CreateVersion7](xref:System.Guid.CreateVersion7). ## RELATED LINKS diff --git a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-76.md b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-76.md index aeae865fa72..491eddc9e23 100644 --- a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-76.md +++ b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-76.md @@ -30,6 +30,9 @@ PowerShell 7.6 includes the following updated modules: - Convert `-ChildPath` parameter to `string[]` for `Join-Path` cmdlet ([#24677][24677]) (Thanks @ArmaanMcleod!) - Remove trailing space from event source name ([#24192][24192]) (Thanks @MartinGC94!) +- `New-Guid` now generates Version 7 (time-sortable) UUIDs by default instead of Version 4 + (random). The output format is unchanged. Scripts that depend on fully random GUIDs should use + `[guid]::NewGuid()` directly. ([#27033][27033]) ## Tab completion improvements @@ -89,6 +92,8 @@ PowerShell 7.6 includes the following updated modules: ## Cmdlet improvements +- Change `New-Guid` to generate UUID v7 by default using `Guid.CreateVersion7()` + ([#27033][27033]) - Add implicit localization fallback to `Import-LocalizedData` ([#19896][19896]) (Thanks @chrisdent-de!) - Add `-Delimiter` parameter to `Get-Clipboard` ([#26572][26572]) (Thanks @MartinGC94!) @@ -302,3 +307,4 @@ This release includes the following experimental features: [26564]: https://github.com/PowerShell/PowerShell/pull/26564 [26571]: https://github.com/PowerShell/PowerShell/pull/26571 [26572]: https://github.com/PowerShell/PowerShell/pull/26572 +[27033]: https://github.com/PowerShell/PowerShell/pull/27033