Skip to content

Change New-Guid to generate UUID v7 by default#26256

Closed
Copilot wants to merge 3 commits intomasterfrom
copilot/add-uuid-v7-support
Closed

Change New-Guid to generate UUID v7 by default#26256
Copilot wants to merge 3 commits intomasterfrom
copilot/add-uuid-v7-support

Conversation

Copy link
Contributor

Copilot AI commented Oct 20, 2025

Summary

This PR updates the New-Guid cmdlet to generate UUID version 7 GUIDs by default, replacing the previous UUID version 4 generation. This change was decided by @PowerShell/wg-powershell-cmdlets based on the belief that users of New-Guid are primarily looking for a GUID/UUID and don't care about the technical aspects, while technical users who need specific versions can call the .NET APIs directly.

What Changed

  • New-Guid now uses Guid.CreateVersion7() instead of Guid.NewGuid()
  • XML documentation updated to reflect UUID v7 generation and provide guidance on accessing specific versions
  • Tests added to validate UUID v7 format and behavior

Benefits of UUID v7

UUID v7 offers several advantages over UUID v4 for modern applications:

  • Time-ordered: Contains a Unix timestamp in the first 48 bits, enabling natural sorting by creation time
  • Better Database Performance: Sequential nature improves database indexing and reduces fragmentation
  • Sortable: GUIDs can be ordered chronologically without additional timestamp columns
  • Maintains Security: Uses cryptographically secure randomness for the remaining bits

Example:

PS> New-Guid
019a03f1-594e-7686-878a-896021153344
             └─┘
              └─ version = 7 (time-ordered)

Backward Compatibility

Fully backward compatible - All existing parameters work unchanged:

  • -Empty parameter continues to work as before
  • -InputObject parameter continues to work as before
  • Pipeline input continues to work as before
  • Output type remains System.Guid

Migration Notes

No action required for existing scripts - they will continue to work. The cmdlet interface is unchanged.

For users who need specific UUID versions:

# UUID v7 (new default)
New-Guid

# UUID v7 with specific timestamp
[Guid]::CreateVersion7()
[Guid]::CreateVersion7([DateTimeOffset]::UtcNow)

# UUID v4 (previous default)
[Guid]::NewGuid()

Technical Details

  • Requires .NET 9.0+ where Guid.CreateVersion7() was introduced
  • UUID version field (character at index 14 in string format) is '7'
  • Timestamp portion enables natural ordering and improved database performance
  • Random portion maintains uniqueness guarantees
Original prompt

This section details on the original issue you should resolve

<issue_title>Add UUID v7 support to New-Guid</issue_title>
<issue_description>### Summary of the new feature / enhancement

Dotnet 9 got support for creating UUID v7 GUIDs.

This could be useful in PowerShell too.

Proposed technical implementation details (optional)

  • Default to v4 like now, but add optional switch for UUID v7, and optional DateTimeOffset as input.
  • New cmdlet New-Ulid?</issue_description>

<agent_instructions>The @PowerShell/wg-powershell-cmdlets discussed this, we believe that users of New-Guid are only looking for a GUID/UUID and don't care about the technical aspects of it. As such, we believe it's better to move to the newer v7 UUID for the cmdlet. Users who want to differentiate between v7 and v4 (previous) are already technical enough to call the [Guid]::CreateVersion7() or [Guid]::NewGuid() for themselves. The docs should be updated to reflect this change and examples using PowerShell to call .NET APIs for specific versions of GUIDs.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@iSazonov There are some great [discussions](https://github.com/dotnet/runtime/issues/103658) in .NET repository. It clearly states that users consider which UUID version with a higher number to be better than which version with a lower number, and they also do not understand which version has its own scope. So they decided not to enhance the Guid class, but to make a separate specific (low level) API for experts.

The Guid class implements version 4, which is strong crypto, and New-Guid follows this most secure approach. The use of other UUID versions should be in community modules designed for special scenarios.

@SteveL-MSFT It's not clear to me if there's a downside to simply having `New-Guid` generate v7 UUIDs @SteveL-MSFT The @PowerShell/wg-powershell-cmdlets discussed this, we believe that users of `New-Guid` are only looking for a GUID/UUID and don't care about the technical aspects of it. As such, we believe it's better to move to the newer v7 UUID for the cmdlet. Users who want to differentiate between v7 and v4 (previous) are already technical enough to call the `[Guid]::CreateVersion7()` or `[Guid]::NewGuid()` for themselves. The docs should be updated to reflect this change and examples using PowerShell to call .NET APIs for specific versions of GUIDs.

Fixes #24895


💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Copilot AI changed the title [WIP] Add UUID v7 support to New-Guid cmdlet Change New-Guid to generate UUID v7 by default Oct 20, 2025
Copilot AI requested a review from TravisEz13 October 20, 2025 23:33
@TravisEz13 TravisEz13 requested a review from Copilot October 20, 2025 23:41
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR updates the New-Guid cmdlet to generate UUID version 7 GUIDs by default instead of UUID version 4, providing time-ordered identifiers that offer better database performance and natural sortability while maintaining backward compatibility.

Key Changes:

  • Modified default GUID generation from Guid.NewGuid() (v4) to Guid.CreateVersion7() (v7)
  • Updated XML documentation to explain the UUID v7 default and how to access specific versions
  • Added tests to verify UUID v7 format and time-ordered behavior

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File Description
NewGuidCommand.cs Changed default GUID generation method to CreateVersion7() and updated documentation
New-Guid.Tests.ps1 Added tests to verify UUID v7 format and time-ordered properties

Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.

@TravisEz13 TravisEz13 added the CL-General Indicates that a PR should be marked as a general cmdlet change in the Change Log label Oct 20, 2025
@xtqqczze
Copy link
Contributor

Fixes #20896

There seems to be a pattern of Copilot fabricating issue numbers.

@jborean93
Copy link
Collaborator

Should we be defaulting to v7, seems like we should take this opportunity to expose some selector to specify which version to use and keep the default at 4. If .NET ever exposes a way to do things like v5 with a namespace or if we want to expose the DateTImeOffset parameter to the end user.

@TravisEz13
Copy link
Member

Should we be defaulting to v7, seems like we should take this opportunity to expose some selector to specify which version to use and keep the default at 4. If .NET ever exposes a way to do things like v5 with a namespace or if we want to expose the DateTImeOffset parameter to the end user.

already decided in the issue.

@microsoft-github-policy-service microsoft-github-policy-service bot added the Waiting on Author The PR was reviewed and requires changes or comments from the author before being accept label Oct 25, 2025
@microsoft-github-policy-service
Copy link
Contributor

This pull request has been automatically marked as stale because it has been marked as requiring author feedback but has not had any activity for 15 days. It will be closed if no further activity occurs within 10 days of this comment.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CL-General Indicates that a PR should be marked as a general cmdlet change in the Change Log Stale Waiting on Author The PR was reviewed and requires changes or comments from the author before being accept

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add UUID v7 support to New-Guid

5 participants