Get-SecureRandom
Gets a random number, or selects objects randomly from a collection.
Syntax
Get-SecureRandom
[[-Maximum] <Object>]
[-Minimum <Object>]
[-Count <Int32>]
[<CommonParameters>] Get-SecureRandom
[-InputObject] <Object[]>
[-Count <Int32>]
[<CommonParameters>] Get-SecureRandom
[-InputObject] <Object[]>
[-Shuffle]
[<CommonParameters>] Description
The Get-SecureRandom cmdlet gets a randomly selected number. If you submit a collection of objects
to Get-SecureRandom, it gets one or more randomly selected objects from the collection.
Without parameters or input, a Get-SecureRandom command returns a randomly selected 32-bit
unsigned integer between 0 (zero) and [int32]::MaxValue.
You can use the parameters of Get-SecureRandom to specify the minimum and maximum values and the
number of objects returned from a collection.
Get-SecureRandom generates cryptographically secure randomness using the
RandomNumberGenerator class.
Examples
Example 1: Get a random integer
This command gets a random integer between 0 (zero) and Int32.MaxValue.
Get-SecureRandom
3951433Example 2: Get a random integer between 0 and 99
Get-SecureRandom -Maximum 100
47Example 3: Get a random integer between -100 and 99
Get-SecureRandom -Minimum -100 -Maximum 100
56Example 4: Get a random floating-point number
This command gets a random floating-point number greater than or equal to 10.7 and less than 20.93.
Get-SecureRandom -Minimum 10.7 -Maximum 20.93
18.08467273887Example 5: Get a random integer from an array
This command gets a randomly selected number from the specified array.
1, 2, 3, 5, 8, 13 | Get-SecureRandom
8Example 6: Get several random integers from an array
This command gets three randomly selected numbers in random order from an array.
1, 2, 3, 5, 8, 13 | Get-SecureRandom -Count 3
3
1
13Example 7: Randomize an entire collection
You can use the Shuffle parameter to return the entire collection in a random order.
1, 2, 3, 5, 8, 13 | Get-SecureRandom -Shuffle
2
3
5
1
8
13Example 8: Get a random non-numeric value
This command returns a random value from a non-numeric collection.
"red", "yellow", "blue" | Get-SecureRandom
yellowExample 9: Get random files
These commands get a randomly selected sample of 50 files from the C: drive of the local computer.
$Files = Get-ChildItem -Path C:\* -Recurse
$Sample = $Files | Get-SecureRandom -Count 50Example 10: Roll fair dice
This example rolls a fair die 1200 times and counts the outcomes. The first command,
ForEach-Object repeats the call to Get-SecureRandom from the piped in numbers (1-6). The results
are grouped by their value with Group-Object and formatted as a table with Select-Object.
1..1200 | ForEach-Object {
1..6 | Get-SecureRandom
} | Group-Object | Select-Object Name,Count
Name Count
---- -----
1 206
2 199
3 196
4 226
5 185
6 188Example 11: Use the Count parameter
You can use the Count parameter without piping objects to Get-SecureRandom. The following
example gets three random numbers less than 10.
Get-SecureRandom -Count 3 -Maximum 10
9
0
8Example 12: Use the InputObject parameter with an empty string or $null
In this example, the InputObject parameter specifies an array that contains an empty string
('') and $null.
Get-SecureRandom -InputObject @('a','',$null)Get-SecureRandom returns either a, empty string, or $null. The empty sting displays as a blank
line and $null returns to a PowerShell prompt.
Parameters
-Count
Specifies the number of random objects to return. The default is 1.
When used with InputObject containing a collection:
- Each randomly selected item is returned only once.
- If the value of Count exceeds the number of objects in the collection, all objects in the collection are returned in random order.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-InputObject
Specifies a collection of objects. Get-SecureRandom gets randomly selected objects in random order
from the collection up to the number specified by Count. Enter the objects, a variable that
contains the objects, or a command or expression that gets the objects. You can also pipe a
collection of objects to Get-SecureRandom.
The InputObject parameter accepts arrays that can contain an empty
string or $null. The array can be sent down the pipeline or as an InputObject parameter value.
| Type: | Object[] |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Maximum
Specifies a maximum value for the random number. Get-SecureRandom returns a value that's less than
the maximum (not equal). Enter an integer, a double-precision floating-point number, or an object
that can be converted to an integer or double, such as a numeric string ("100").
The value of Maximum must be greater than (not equal to) the value of Minimum. If the value
of Maximum or Minimum is a floating-point number, Get-SecureRandom returns a randomly
selected floating-point number.
On a 64-bit computer, if the value of Minimum is a 32-bit integer, the default value of Maximum is Int32.MaxValue.
If the value of Minimum is a double (a floating-point number), the default value of Maximum is Double.MaxValue. Otherwise, the default value is Int32.MaxValue.
| Type: | Object |
| Position: | 0 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Minimum
Specifies a minimum value for the random number. Enter an integer, a double-precision floating-point number, or an object that can be converted to an integer or double, such as a numeric string ("100"). The default value is 0 (zero).
The value of Minimum must be less than (not equal to) the value of Maximum. If the value of
Maximum or Minimum is a floating-point number, Get-SecureRandom returns a randomly
selected floating-point number.
| Type: | Object |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Shuffle
Returns the entire collection in a randomized order.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Inputs
You can pipe any object to this cmdlet. It selects values randomly from the piped objects.
Outputs
This cmdlet returns an integer or floating-point number, or an object selected randomly from a submitted collection.
Notes
Get-SecureRandom doesn't always return the same data type as the input value. The following table
shows the output type for each of the numeric input types.
| Input Type | Output Type |
|---|---|
| SByte | Double |
| Byte | Double |
| Int16 | Double |
| UInt16 | Double |
| Int32 | Int32 |
| UInt32 | Double |
| Int64 | Int64 |
| UInt64 | Double |
| Double | Double |
| Single | Double |
Related Links
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for