This is the built-in help made by Microsoft for the document 'about_hash_tables', in PowerShell version 2 - as retrieved from
Windows version 'Microsoft® Windows Vista™ Ultimate ' PowerShell help files on 2016-06-24.
For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.
TOPIC
about_Hash_Tables
SHORT DESCRIPTION
Describes how to create, use, and sort hash tables in Windows PowerShell.
LONG DESCRIPTION
A hash table, also known as a dictionary or associative array, is a
compact data structure that stores one or more name/value pairs. For
example, a hash table might contain a series of names and employee IDs,
computer names and IP addresses, or message IDs and message text.
Hash tables are frequently used because they are very efficient for finding
and retrieving data. You can use hash tables to store lists and to create
calculated properties in Windows PowerShell. And, Windows PowerShell has a
cmdlet, ConvertFrom-StringData, that converts strings to a hash table.
Creating Hash Tables
The items in a hash table are arranged in name/value pairs, such as:
Msg1="Please enter your password."
Msg2="The path parameter is required."
Msg3="The alias of Get-Command is gcm."
The values are mapped to or associated with the names so that when you
submit the name, Windows PowerShell returns the value.
In Windows PowerShell, the syntax of a hash table is as follows:
@{ <name> = <value>; [<name> = <value> ] ...}
When you create a hash table, follow these guidelines:
- Begin the hash table with an at sign (@).
- Enclose the hash table in braces ({}).
- Enter one or more name-value pairs for the content of the hash
table.
- Use an equal sign (=) to separate each name from its value.
- Use a semicolon (;) to separate the name/value pairs.
- If a name or value contains spaces, enclose it in quotation marks.
For example, a hash table of the previous user messages looks like this:
@{
Msg1="Please enter your password.";
Msg2="The path parameter is required.";
Msg3="The alias of Get-Command is gcm.";
}
To use a hash table in scripts and commands, save it in a variable. The
value of the variable is a hash table object
(System.Collections.Hashtable), and each name in the name/value pairs
is a property of the hash table object.
The following commands save the user-message hash table in the $a
variable and use the dot method to display the values.
C:\PS> $a = @{
>> Msg1="Please enter your password.";
>> Msg2="The path parameter is required.";
>> Msg3="The alias of Get-Command is gcm.";
>> }
C:\PS> $a
Name Value
---- -----
Msg1 Please enter your password.
Msg3 The alias of Get-Command is gcm.
Msg2 The path parameter is required.
C:\PS> $a.Msg1
Please enter your password.
Hash tables are not limited to one type of data. You can enter any data
type in a hash table, and you can combine data types in a single hash
table. For example, you can build a hash table that contains an integer,
a call to a cmdlet, and a string.
Sorting Hash Tables
To sort the hash table alphabetically by keys or values, use the
GetEnumerator method of hash tables to get the keys and values in the
hash table, and then use the Sort-Object cmdlet to sort them.
For example, the following command sorts the hash table in $a
alphabetically by keys.
C:\PS> $a.getenumerator() | sort-object -property key
Name Value
---- -----
Msg1 Please enter your password.
Msg2 The path parameter is required.
Msg3 The alias of Get-Command is gcm.
The following command uses the same method to sort the hash values in
descending order.
C:\PS> $a.getenumerator() | sort-object -property value -descending
Name Value
---- -----
Msg2 The path parameter is required.
Msg3 The alias of Get-Command is gcm.
Msg1 Please enter your password.
ConvertFrom-StringData
The ConvertFrom-StringData cmdlet converts a string or a here-string of
name/value pairs into a hash table. You can use the
ConvertFrom-StringData cmdlet safely in the Data section of a script,
and you can use it with the Import-LocalizedData cmdlet to display user
messages in the user-interface (UI) culture of the current user.
Here-strings are especially useful when the values in the hash table
include quotation marks. (For more information about here-strings, see
about_Quoting_Rules.)
The following example shows how to create a here-string of the user
messages in the previous example and how to use ConvertFrom-StringData
to convert them from a string into a hash table.
The following command creates a here-string of the name/value pairs and
then saves it in the $string variable.
C:\PS> $string = @"
Msg1="Please enter your password."
Msg2="The path parameter is required."
Msg3="The alias of Get-Command is gcm."
"@
This command uses the ConvertFrom-StringData cmdlet to convert the
here-string into a hash table.
C:\PS> convertfrom-stringdata $string
Name Value
---- -----
Msg3 "The alias of Get-Command is gcm."
Msg2 "The path parameter is required."
Msg1 "Please enter your password."
SEE ALSO
about_Arrays
about_Quoting_Rules
about_Script_Internationalization
ConvertFrom-StringData
Import-LocalizedData