Example
NAME
ConvertTo-Html
SYNOPSIS
Converts Microsoft .NET Framework objects into HTML that can be displayed i
n a Web browser.
SYNTAX
ConvertTo-Html [[-Head] ] [[-Title] ] [[-Body]
] [-CssUri ] [[-Property] ] [-As ] [-InputObject ] [-PostContent ] [-PreContent ] []
ConvertTo-Html [-Fragment] [[-Property] ] [-As ] [-InputO
bject ] [-PostContent ] [-PreContent ] []
DESCRIPTION
The ConvertTo-Html cmdlet converts .NET Framework objects into HTML that ca
n be displayed in a Web browser. You can use this cmdlet to display the out
put of a command in a Web page.
You can use the parameters of ConvertTo-Html to select object properties, t
o specify a table or list format, to specify the HTML page title, to add te
xt before and after the object, and to return only the table or list fragme
nt, instead of a strict DTD page.
When you submit multiple objects to ConvertTo-Html, Windows PowerShell crea
tes the table (or list) based on the properties of the first object that yo
u submit. If the remaining objects do not have one of the specified propert
ies, the property value of that object is an empty cell. If the remaining o
bjects have additional properties, those property values are not included i
n the file.
PARAMETERS
-As
Determines whether the object is formatted as a table or a list. Valid
values are TABLE and LIST. The default value is TABLE.
The TABLE value generates an HTML table that resembles the Windows Powe
rShell table format. The header row displays the property names. Each t
able row represents an object and displays the object's values for each
property.
The LIST value generates a two-column HTML table for each object that
resembles the Windows PowerShell list format. The first column displays
the property name; the second column displays the property value.
Required? false
Position? named
Default value Table
Accept pipeline input? false
Accept wildcard characters? false
-Body
Specifies the text to add after the opening '' tag. By default,
there is no text in that position.
Required? false
Position? 4
Default value No text.
Accept pipeline input? false
Accept wildcard characters? false
-CssUri
Specifies the Uniform Resource Identifier (URI) of the cascading style
sheet (CSS) that is applied to the HTML file. The URI is included in a
style sheet link in the output.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Fragment []
Generates only an HTML table. The HTML, HEAD, TITLE, and BODY tags are
omitted.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Head
Specifies the content of the tag. The default is "HTML TA
BLE ". If you use the Head parameter, the Title parameter is ig
nored.
Required? false
Position? 2
Default value HTML TABLE
Accept pipeline input? false
Accept wildcard characters? false
-InputObject
Specifies the objects to be represented in HTML. Enter a variable that
contains the objects or type a command or expression that gets the obje
cts.
If you use this parameter to submit multiple objects, such as all of th
e services on a computer, ConvertTo-Html creates a table that displays
the properties of a collection or of an array of objects (System.Object
[]). To create a table of the individual objects, use the pipeline oper
ator to pipe the objects to ConvertTo-Html.
Required? false
Position? named
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
-PostContent
Specifies text to add after the closing TABLE tag. By default, there
is no text in that position.
Required? false
Position? named
Default value No text
Accept pipeline input? false
Accept wildcard characters? false
-PreContent
Specifies text to add before the opening TABLE' tag. By default, there
is no text in that position.
Required? false
Position? named
Default value No text
Accept pipeline input? false
Accept wildcard characters? false
-Property
Includes the specified properties of the objects in the HTML.
Required? false
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Title
Specifies a title for the HTML file, that is, the text that appears bet
ween the tags.
Required? false
Position? 3
Default value
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".
INPUTS
System.Management.Automation.PSObject
You can pipe any .NET object to ConvertTo-Html.
OUTPUTS
System.String
ConvertTo-Html returns series of strings that comprise valid HTML.
NOTES
To use this cmdlet, pipe one or more objects to the cmdlet or use the I
nputObject parameter to specify the object. When the input consists of
multiple objects, the output of these two methods is quite different.
-- When you pipe multiple objects to a cmdlet, Windows PowerShell send
s the objects to the cmdlet one at a time. As a result, ConvertTo-Html
creates a table that displays the individual objects. For example, if y
ou pipe the processes on a computer to ConvertTo-Html, the resulting ta
ble displays all of the processes.
-- When you use the InputObject parameter to submit multiple objects,
ConvertTo-Html receives these objects as a collection or as an array. A
s a result, it creates a table that displays the array and its properti
es, not the items in the array. For example, if you use InputObject to
submit the processes on a computer to ConvertTo-Html, the resulting tab
le displays an object array (System.Object[]) and its properties.
To comply with the XHTML Strict DTD,the DOCTYPE tag is modified accordi
ngly:
(<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http:/
/www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">)
-------------------------- EXAMPLE 1 --------------------------
C:\PS>convertto-html -inputobject (get-date)
Description
-----------
This command creates an HTML page that displays the properties of the curre
nt date. It uses the InputObject parameter to submit the results of a Get-D
ate command to the ConvertTo-Html cmdlet.
-------------------------- EXAMPLE 2 --------------------------
C:\PS>get-alias | convertto-html > aliases.htm
C:\PS> invoke-item aliases.htm
Description
-----------
This command creates an HTML page that lists the Windows PowerShell aliases
in the current console.
The command uses the Get-Alias cmdlet to get the aliases. It uses the pipel
ine operator (|) to send the aliases to the ConvertTo-Html cmdlet, which cr
eates the HTML page.
-------------------------- EXAMPLE 3 --------------------------
C:\PS>get-eventlog -logname "Windows PowerShell | convertto-html > pslog.ht
m
Description
-----------
This command creates an HTML page called pslog.htm that displays the events
in the Windows PowerShell event log on the local computer.
It uses the Get-EventLog cmdlet to get the events in the Windows PowerShell
log and then uses the pipeline operator (|) to send the events to the Conv
ertTo-Html cmdlet.
The command also uses the redirection operator (>) to send the HTML code to
the pslog.htm file.
-------------------------- EXAMPLE 4 --------------------------
C:\PS>get-process | convertto-html -property Name, Path, Company -title "Pr
ocess Information" > proc.htm; ii proc.htm
Description
-----------
These commands create and open an HTML page that lists the name, path, and
company of the processes on the local computer.
The first command uses the Get-Process cmdlet to get objects that represent
the processes running on the computer. The command uses the pipeline opera
tor (|) to send the process objects to the ConvertTo-Html cmdlet.
The command uses the Property parameter to select three properties of the p
rocess objects to be included in the table. The command uses the Title para
meter to specify a title for the HTML page. The command also uses the redir
ection operator (>) to send the resulting HTML to a file named Proc.htm.
The second command uses the Invoke-Item cmdlet (alias = ii) to open the Pro
c.htm in the default browser. The two commands are separated by a semicolon
(;).
-------------------------- EXAMPLE 5 --------------------------
C:\PS>get-service | convertto-html -CssUri "test.css"
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.
w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>HTML TABLE
...
Description
-----------
This command creates an HTML page of the service objects that the Get-Servi
ce cmdlet returns. The command uses the CssUri parameter to specify a casca
ding style sheet for the HTML page.
The CssUri parameter adds an additional "get-service | convertto-html -as LIST > services.htm
Description
-----------
This command creates an HTML page of the service objects that the Get-Servi
ce cmdlet returns. The command uses the As parameter to specify a list form
at. The redirection operator (>) sends the resulting HTML to the Services.h
tm file.
-------------------------- EXAMPLE 7 --------------------------
C:\PS>get-date | cth -fragment
Description
-----------
This command uses ConvertTo-Html to generate an HTML table of the current d
ate. The command uses the Get-Date cmdlet to get the current date. It uses
a pipeline operator (|) to send the results to the ConvertTo-Html cmdlet (a
liased as "cth").
The ConvertTo-Html command includes the Fragment parameter, which limits th
e output to an HTML table. As a result, the other elements of an HTML page,
such as the and tags, are omitted.
-------------------------- EXAMPLE 8 --------------------------
C:\PS>get-eventlog -log "Windows PowerShell" | convertto-html -property id,
level, task
Description
-----------
This command uses the Get-EventLog cmdlet to get events from the "Windows P
owerShell" event log.
It uses a pipeline operator (|) to send the events to the ConvertTo-Html cm
dlet, which converts the events to HTML format.
The ConvertTo-Html command uses the Property parameter to select only the I
D, Level, and Task properties of the event.
-------------------------- EXAMPLE 9 --------------------------
C:\PS>get-service A* | ConvertTo-Html -title "Windows Services: Server01" -
body (get-date) -pre "Generated by Corporate IT
" -post "For details, contact Corporate IT." > services.htm; ii services.h
tm
Description
-----------
This command creates and opens a Web page that displays the services on the
computer that begin with "A". It uses the Title, Body, PreContent, and Pos
tContent parameters of ConvertTo-Html to customize the output.
The first part of the command uses the Get-Service cmdlet to get the servic
es on the computer that begin with "A". The command uses a pipeline operato
r (|) to send the results to the ConvertTo-Html cmdlet. The command uses a
redirection operator (>) to send the output to the Services.htm file.
A semicolon (;) ends the first command and starts a second command, which u
ses the Invoke-Item cmdlet (alias = "ii") to open the Services.htm file in
the default browser.
RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113290
ConvertTo-CSV
ConvertTo-Xml
NAME
ConvertFrom-StringData
SYNOPSIS
Converts a string containing one or more key/value pairs to a hash table.
SYNTAX
ConvertFrom-StringData [-StringData] []
DESCRIPTION
The ConvertFrom-StringData cmdlet converts a string that contains one or mo
re key/value pairs into a hash table. Because each key/value pair must be
on a separate line, here-strings are often used as the input format.
The ConvertFrom-StringData cmdlet is considered to be a safe cmdlet that ca
n be used in the DATA section of a script or function. When used in a DATA
section, the contents of the string must conform to the rules for a DATA se
ction. For more information, see about_Data_Sections.
PARAMETERS
-StringData
Specifies the string to be converted. You can use this parameter or pip
e a string to ConvertFrom-StringData. The parameter name is optional.
The value of this parameter must be a string that is enclosed in single
quotation marks (a single-quoted string) or a string that is enclosed
in double quotation marks (a double-quoted string) or a here-string con
taining one or more key/value pairs. Each key/value pair must be on a s
eparate line, or each pair must be separated by newline characters (`n)
.
You can include comments in the string, but the comments cannot be on t
he same line as a key/value pair. The comments are not included in the
hash table.
A here-string is a string consisting of one or more lines within which
quotation marks are interpreted literally. For more information, see ab
out_Quoting_Rules.
Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".
INPUTS
System.String
You can pipe a string containing a key/value pair to ConvertFrom-String
Data.
OUTPUTS
System.Collections.Hashtable
ConvertFrom-StringData returns a hash table that it creates from the ke
y/value pairs.
NOTES
A here-string is a string consisting of one or more lines within which
quotation marks are interpreted literally. For more information, see ab
out_Quoting_Rules.
ConvertFrom-StringData can be useful in scripts that display user messa
ges in multiple spoken languages. You can use the dictionary-style hash
tables to isolate text strings from code, such as in resource files, a
nd to format the text strings for use in translation tools.
-------------------------- EXAMPLE 1 --------------------------
C:\PS>$here = @'
Msg1 = The string parameter is required.
Msg2 = Credentials are required for this command.
Msg3 = The specified variable does not exist.
'@
C:\PS> convertfrom-stringdata -stringdata $here
Name Value
---- -----
Msg3 The specified variable does not exist.
Msg2 Credentials are required for this command.
Msg1 The string parameter is required.
Description
-----------
These commands convert a single-quoted here-string of user messages into a
hash table. In a single-quoted string, values are not substituted for varia
bles and expressions are not evaluated.
The first command creates a here-string and saves it in the $here variable.
The second command uses the ConvertFrom-StringData cmdlet to convert the he
re-string in the $here variable to a hash table.
-------------------------- EXAMPLE 2 --------------------------
C:\PS>$p = @"
ISE = Windows PowerShell Integrated Scripting Environment
"@
C:\PS> $p | get-member
TypeName: System.String
Name MemberType Definition
---- ---------- ----------
Clone Method System.Object Clone()
...
C:\PS> $hash = convertfrom-stringdata -stringdata $p
C:\PS> $hash | get-member
TypeName: System.Collections.Hashtable
Name MemberType Definition
---- ---------- ----------
Add Method System.Void Add(Object key, Object
...
Description
-----------
These commands demonstrate that ConvertFrom-StringData actually converts a
here-string to a hash table.
The first command creates a double-quoted here-string that includes one key
/value" pair and saves it in the $p variable.
The second command uses a pipeline operator (|) to send the $p variable to
the Get-Member cmdlet. The result shows that $p is a string (System.String)
.
The third command uses the ConvertFrom-StringData cmdlet to convert the her
e-string in $p to a hash table. The command stores the result in the $hash
variable.
The final command uses a pipeline operator (|) to send the $hash variable t
o the Get-Member cmdlet. The result shows that the content of the $hash var
iable is a hash table (System.Collections.Hashtable).
-------------------------- EXAMPLE 3 --------------------------
C:\PS>convertfrom-stringdata -stringdata @'
Name = Disks.ps1
# Category is optional.
Category = Storage
Cost = Free
'@
Name Value
---- -----
Cost Free
Category Storage
Name Disks.ps1
Description
-----------
This command converts a single-quoted here-string that contains multiple ke
y/value pairs into a hash table.
In this command, the value of the StringData parameter is a here-string, in
stead of a variable that contains a here-string. Either format is valid.
The here-string includes a comment about one of the strings. Comments are v
alid in strings, provided that the comment is on a different line than a ke
y/value pair.
-------------------------- EXAMPLE 4 --------------------------
C:\PS>$a = convertfrom-stringdata -stringdata "Top = Red `n Bottom = Blue"
C:\PS> "Top = " + $a.Top
Top = Red
C:\PS> "Bottom = " + $a.Bottom
Bottom = Blue
Description
-----------
This example converts a regular double-quoted string (not a here-string) in
to a hash table and saves it in the $a variable.
To satisfy the condition that each key/value pair must be on a separate lin
e, it uses the Windows PowerShell newline character (`n) to separate the pa
irs.
The result is a hash table of the input. The remaining commands display the
output.
-------------------------- EXAMPLE 5 --------------------------
C:\PS>$TextMsgs = DATA {
ConvertFrom-StringData @'
Text001 = The $Notebook variable contains the name of the user's sy
stem notebook.
Text002 = The $MyNotebook variable contains the name of the user's
private notebook.
'@
}
C:\PS> $TextMsgs.Text001
The $Notebook variable contains the name of the user's system notebook.
C:\PS> $TextMsgs.Text002
The $MyNotebook variable contains the name of the user's private notebook.
Description
-----------
This example shows a ConvertFrom-StringData command used in the DATA sectio
n of a script. The statements below the DATA section display the text to th
e user.
Because the text includes variable names, it must be enclosed in a single-q
uoted string so that the variables are interpreted literally and not expand
ed. Variables are not permitted in the DATA section.
-------------------------- EXAMPLE 6 --------------------------
C:\PS>$here = @'
Msg1 = The string parameter is required.
Msg2 = Credentials are required for this command.
Msg3 = The specified variable does not exist.
'@
C:\PS> $hash = $here | convertfrom-stringdata
C:\PS> $hash
Name Value
---- -----
Msg3 The specified variable does not exist.
Msg2 Credentials are required for this command.
Msg1 The string parameter is required.
Description
-----------
This example shows that you can use a pipeline operator (|) to send a strin
g to ConvertFrom-StringData.
The first command saves a here-string in the $here variable. The second com
mand uses a pipeline operator (|) to send the $here variable to ConvertFrom
-StringData. The command saves the result in the $hash variable.
The final command displays the contents of the $hash variable.
RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113288
about_Data_Sections
about_Quoting_Rules
about_Script_Internationalization
NAME
ConvertTo-CSV
SYNOPSIS
Converts Microsoft .NET Framework objects into a series of comma-separated
value (CSV) variable-length strings.
SYNTAX
ConvertTo-CSV [[-Delimiter] ] [-InputObject] [-NoTypeInfor
mation] []
ConvertTo-CSV [-UseCulture] [-InputObject] [-NoTypeInformation]
[]
DESCRIPTION
The ConvertTo-CSV cmdlet returns a series of comma-separated, variable-leng
th (CSV) strings that represents the objects that you submit. You can then
use the ConvertFrom-CSV cmdlet to re-create objects from the CSV strings. T
he resulting objects are CSV versions of the original objects that consist
of string representations of the property values and no methods.
You can also use the Export-CSV and Import-CSV cmdlets to convert .NET Fram
ework objects to CSV strings (and back). Export-CSV is the same as ConvertT
o-CSV, except that it saves the CSV strings in a file.
You can use the parameters of the ConvertTo-CSV cmdlet to specify a delimit
er other than a comma or to direct ConvertTo-CSV to use the default delimit
er for the current culture.
For more information, see Export-CSV, and see the Notes section.
PARAMETERS
-Delimiter
Specifies a delimiter to separate the property values. The default is a
comma (,). Enter a character, such as a colon (:).
To specify a semicolon (;), enclose it in quotation marks. Otherwise, i
t will be interpreted as the command delimiter.
Required? false
Position? 2
Default value , (comma)
Accept pipeline input? false
Accept wildcard characters? false
-InputObject
Specifies the objects to export as CSV strings. Enter a variable that c
ontains the objects or type a command or expression that gets the objec
ts. You can also pipe objects to ConvertTo-CSV.
Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue, ByPropertyName)
Accept wildcard characters? false
-NoTypeInformation []
Omits the type information header from the output. By default, the stri
ng in the output contains "#TYPE " followed by the fully-qualified name
of the type of the .NET Framework object.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-UseCulture []
Uses the list separator for the current culture as the data delimiter.
The default is a comma (,).
This parameter is very useful in scripts that are being distributed to
users worldwide. To find the list separator for a culture, use the foll
owing command: (Get-Culture).TextInfo.ListSeparator.
Required? false
Position? named
Default value Comma
Accept pipeline input? false
Accept wildcard characters? false
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".
INPUTS
System.Management.Automation.PSObject
You can pipe any .NET Framework object to ConvertTo-CSV.
OUTPUTS
System.String
The CSV output is returned as a collection of strings.
NOTES
In CSV format, each object is represented by a comma-separated list of
its property value. The property values are converted to strings (by us
ing the ToString() method of the object), so they are generally represe
nted by the name of the property value. ConvertTo-CSV does not export t
he methods of the object.
The format of the resulting CSV strings is as follows:
-- The first string consists of '#TYPE ' followed by the fully-qualifie
d name of the .NET Framework type of the object, such as #TYPE System.D
iagnostics.Process. To suppress this string, use the NoTypeInformation
parameter.
-- The next string represents the column headers. It contains a comma-s
eparated list of the names of all the properties of the first object.
-- The remaining strings consist of comma-separated lists of the proper
ty values of each object.
When you submit multiple objects to ConvertTo-CSV, ConvertTo-CSV orders
the strings based on the properties of the first object that you submi
t. If the remaining objects do not have one of the specified properties
, the property value of that object is null, as represented by two cons
ecutive commas. If the remaining objects have additional properties, th
ose property values are ignored.
-------------------------- EXAMPLE 1 --------------------------
C:\PS>get-process powershell | convertto-csv
#TYPE System.Diagnostics.Process
"__NounName","Name","Handles","VM","WS","PM","NPM","Path","Company","CPU","
FileVersion","ProductVersion","Description",
"Product","BasePriority","ExitCode","HasExited","ExitTime","Handle","Handle
Count","Id","MachineName","MainWindowHandle"
,"MainWindowTitle","MainModule","MaxWorkingSet","MinWorkingSet","Modules","
NonpagedSystemMemorySize","NonpagedSystemMem
orySize64","PagedMemorySize","PagedMemorySize64","PagedSystemMemorySize","P
agedSystemMemorySize64","PeakPagedMemorySize
","PeakPagedMemorySize64","PeakWorkingSet","PeakWorkingSet64","PeakVirtualM
emorySize","PeakVirtualMemorySize64","Priori
tyBoostEnabled","PriorityClass","PrivateMemorySize","PrivateMemorySize64","
PrivilegedProcessorTime","ProcessName","Proc
essorAffinity","Responding","SessionId","StartInfo","StartTime","Synchroniz
ingObject","Threads","TotalProcessorTime","U
serProcessorTime","VirtualMemorySize","VirtualMemorySize64","EnableRaisingE
vents","StandardInput","StandardOutput","Sta
ndardError","WorkingSet","WorkingSet64","Site","Container"
"Process","powershell","216","597544960","60399616","63197184","21692","C:\
WINDOWS\system32\WindowsPowerShell\v1.0\powe
rshell.exe","Microsoft Corporation","3.4788223","6.1.6587.1 (fbl_srv_powers
hell(nigels).070711-0102)","6.1.6587.1","Win
dows PowerShell","Microsoft® Windows® Operating System","8",,"False",,"860"
,"216","5132",".","5636936","Windows PowerSh
ell 2.0 (04/17/2008 00:10:40)","System.Diagnostics.ProcessModule (powershel
l.exe)","1413120","204800","System.Diagnosti
cs.ProcessModuleCollection","21692","21692","63197184","63197184","320080",
"320080","63868928","63868928","60715008","6
0715008","598642688","598642688","True","Normal","63197184","63197184","00:
00:00.2028013","powershell","15","True","1",
"System.Diagnostics.ProcessStartInfo","4/21/2008 3:49:19 PM",,"System.Diagn
ostics.ProcessThreadCollection","00:00:03.51
00225","00:00:03.3072212","597544960","597544960","False",,,,"60399616","60
399616",,
Description
-----------
This command converts a single process object to CSV format. The command us
es the Get-Process cmdlet to get the PowerShell process on the local comput
er. It uses a pipeline operator (|) to send the command to the ConvertTo-CS
V cmdlet, which converts it to a series of comma-separated strings.
-------------------------- EXAMPLE 2 --------------------------
C:\PS>$date = get-date
C:\PS> convertto-csv -inputobject $date -delimiter ";" -notypeinformation
Description
-----------
This example converts a date object to CSV format.
The first command uses the Get-Date cmdlet to get the current date. It save
s it in the $date variable.
The second command uses the ConvertTo-CSV cmdlet to convert the DateTime ob
ject in the $date variable to CSV format. The command uses the InputObject
parameter to specify the object to be converted. It uses the Delimiter para
meter to specify the delimiter that separates the object properties. It use
s the NoTypeInformation parameter to suppress the #TYPE string.
-------------------------- EXAMPLE 3 --------------------------
C:\PS>get-eventlog -log "windows powershell" | convertto-csv -useculture
Description
-----------
This command converts the Windows PowerShell event log on the local compute
r to a series of CSV strings.
The command uses the Get-EventLog cmdlet to get the events in the Windows P
owerShell log. A pipeline operator (|) sends the events to the ConvertTo-CS
V cmdlet, which converts the events to CSV format. The command uses the Use
Culture parameter, which uses the list separator for the current culture as
the delimiter.
RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=135203
Import-CSV
Export-CSV
ConvertFrom-CSV
NAME
ConvertFrom-CSV
SYNOPSIS
Converts object properties in comma-separated value (CSV) format into CSV v
ersions of the original objects.
SYNTAX
ConvertFrom-CSV [[-Delimiter] ] [-InputObject] [-Header
] []
ConvertFrom-CSV -UseCulture [-InputObject] [-Header
] []
DESCRIPTION
The ConvertFrom-CSV cmdlet creates objects from CSV variable-length strings
that are generated by the ConvertTo-CSV cmdlet.
You can use the parameters of the ConvertFrom-CSV cmdlet to specify the col
umn header row, which determines the property names of the resulting object
s, to specify the item delimiter, or to direct ConvertFrom-CSV to use the l
ist separator for the current culture as the delimiter.
The objects that ConvertFrom-CSV creates are CSV versions of the original o
bjects. The property values of the CSV objects are string versions of the p
roperty values of the original objects. The CSV versions of the objects do
not have any methods.
You can also use the Export-CSV and Import-CSV cmdlets to convert objects t
o CSV strings in a file (and back). These cmdlets are the same as the Conve
rtTo-CSV and ConvertFrom-CSV cmdlets, except that they save the CSV strings
in a file.
PARAMETERS
-Delimiter
Specifies the delimiter that separates the property values in the CSV s
trings. The default is a comma (,). Enter a character, such as a colon
(:). To specify a semicolon (;), enclose it in quotation marks.
If you specify a character other than the delimiter used in the CSV str
ings, ConvertFrom-CSV cannot create objects from the CSV strings. Inste
ad, it returns the strings.
Required? false
Position? 2
Default value ','
Accept pipeline input? false
Accept wildcard characters? false
-Header
Specifies an alternate column header row for the imported string. The c
olumn header determines the names of the properties of the object that
ConvertFrom-CSV creates.
Enter a comma-separated list of the column headers. Enclose each item i
n quotation marks (single or double). Do not enclose the header string
in quotation marks. If you enter fewer column headers than there are co
lumns, the remaining columns will have no headers. If you enter more he
aders than there are columns, the extra headers are ignored.
When using the Header parameter, omit the column header string from the
CSV strings. Otherwise, ConvertFrom-CSV creates an extra object from t
he items in the header row.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-InputObject
Specifies the CSV strings to be converted to objects. Enter a variable
that contains the CSV strings or type a command or expression that gets
the CSV strings. You can also pipe the CSV strings to ConvertFrom-CSV.
Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue, ByPropertyName)
Accept wildcard characters? false
-UseCulture []
Use the list separator for the current culture as the string delimiter.
The default is a comma (,).
To find the list separator for a culture, use the following command: (G
et-Culture).TextInfo.ListSeparator. If you specify a character other th
an the delimiter used in the CSV strings, ConvertFrom-CSV cannot create
objects from the CSV strings. Instead, it returns the strings.
Required? true
Position? named
Default value Comma
Accept pipeline input? false
Accept wildcard characters? false
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".
INPUTS
System.String
You can pipe CSV strings to ConvertFrom-CSV.
OUTPUTS
System.Management.Automation.PSObject
ConvertFrom-CSV returns the objects described by the properties in the
CSV strings.
NOTES
Because the imported objects are CSV versions of the object type, they
are not recognized and formatted by the Windows PowerShell type formatt
ing entries that format the non-CSV versions of the object type.
In CSV format, each object is represented by a comma-separated list of
the property values of the object. The property values are converted to
strings (by using the ToString() method of the object), so they are ge
nerally represented by the name of the property value. ConvertTo-Csv do
es not export the methods of the object.
-------------------------- EXAMPLE 1 --------------------------
C:\PS>$p = get-process | convertto-csv
C:\PS> $p | convertfrom-csv
Description
-----------
These commands convert the processes on the local computer into CSV format
and then restore them to object form.
The first command uses the Get-Process cmdlet to get the processes on the l
ocal computer. A pipeline operator (|) sends them to the ConvertTo-CSV cmdl
et, which converts the process object to CSV format. The CSV strings are sa
ved in the $p variable.
The second command uses a pipeline operator to send the CSV strings in the
$p variable to the ConvertFrom-CSV cmdlet. The cmdlet converts the CSV stri
ngs into CSV versions of the original process objects.
-------------------------- EXAMPLE 2 --------------------------
C:\PS>$date = get-date | convertto-csv -delimiter ";"
C:\PS> convertfrom-csv -inputobject $date -delimiter ";"
Description
-----------
These commands convert a data object to CSV format and then to CSV object f
ormat.
The first command uses the Get-Date cmdlet to get the current date and time
. A pipeline object (|) sends the date to the ConvertTo-CSV cmdlets, which
converts the date object to a series of CSV strings. The command uses the D
elimiter parameter to specify a semicolon delimiter. The strings are saved
in the $date variable.
The second command uses the ConvertFrom-CSV cmdlet to convert the CSV strin
gs in the $date variable back to object format. The command uses the InputO
bject parameter to specify the CSV strings and the Delimiter parameter to s
pecify the semicolon delimiter.
-------------------------- EXAMPLE 3 --------------------------
C:\PS>$j = start-job -scriptblock { get-process } | convertto-csv
C:\PS> $header = "MoreData","StatusMessage","Location","Command","State","F
inished","InstanceId","SessionId","Name","ChildJobs","Output","Error","Prog
ress","Verbose","Debug","Warning","StateChanged"
# Delete header from $j
C:\PS> $j = $j[0], $j[2..($j.count - 1)]
$j | convertfrom-csv -header $header
MoreData : True
StatusMessage :
Location : localhost
Command : get-process
State : Running
Finished : System.Threading.ManualResetEvent
InstanceId : 6fcb6578-7f42-4d93-9f23-9937f6aac1a2
SessionId : 1
Name : Job1
ChildJobs : System.Collections.Generic.List`1[System.Management.Automat
ion.Job]
Output : System.Management.Automation.PSDataCollection`1[System.Mana
gement.Automation.PSObject]
Error : System.Management.Automation.PSDataCollection`1[System.Mana
gement.Automation.ErrorRecord]
Progress : System.Management.Automation.PSDataCollection`1[System.Mana
gement.Automation.ProgressRecord]
Verbose : System.Management.Automation.PSDataCollection`1[System.Stri
ng]
Debug : System.Management.Automation.PSDataCollection`1[System.Stri
ng]
Warning : System.Management.Automation.PSDataCollection`1[System.Stri
ng]
StateChanged :
Description
-----------
This example shows how to use the Header parameter of ConvertFrom-Csv to ch
ange the names of properties in the resulting imported object.
The first command uses the Start-Job cmdlet to start a background job that
runs a Get-Process command on the local computer. A pipeline operator (|) s
ends the resulting job object to the ConvertTo-CSV cmdlet, which converts t
he job object to CSV format. An assignment operator (=) saves the resulting
CSV in the $j variable.
The second command saves a header in the $header variable. Unlike the defau
lt header, this header uses "MoreData" instead of "HasMoreData" and "State"
instead of "JobStateInfo".
The third command deletes the original header (the second line) from the CS
V strings and returns it to the $j variable.
The fourth command uses the ConvertFrom-CSV cmdlet to convert the CSV strin
gs to a CSV version of the job object. The command uses a pipeline operator
to send the content in $j to ConvertFrom-CSV. The resulting object has "Mo
reData" and "State" properties, as specified by the header.
-------------------------- EXAMPLE 4 --------------------------
C:\PS>(get-culture).textinfo.listseparator
C:\PS> ConvertFrom-Csv -inputobject $services -UseCulture
Description
-----------
The command uses the ConvertFrom-CSV cmdlet to convert CSV strings of servi
ce objects that had been converted by the ConvertTo-CSV cmdlet. The command
uses the UseCulture parameter to direct ConvertFrom-CSV to use the delimit
er (list separator) of the current culture.
When using the UseCulture parameter, be sure that the list separator of the
current culture matches the delimiter used in the CSV strings. Otherwise,
ConvertFrom-CSV cannot generate objects from the CSV strings.
In this example, a Get-Culture command was used to verify the list separato
r, before the ConvertFrom-CSV command was used.
RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=135201
ConvertTo-CSV
Export-CSV
Import-CSV
NAME
ConvertTo-XML
SYNOPSIS
Creates an XML-based representation of an object.
SYNTAX
ConvertTo-XML [-InputObject] [-As ] [-Depth ] [-NoT
ypeInformation] []
DESCRIPTION
The ConvertTo-Xml cmdlet creates an XML-based representation of one or more
Microsoft .NET Framework objects. To use this cmdlet, pipe one or more obj
ects to the cmdlet, or use the InputObject parameter to specify the object.
When you pipe multiple objects to ConvertTo-XML or use the InputObject para
meter to submit multiple objects, ConvertTo-XML returns a single XML docume
nt that includes representations of all of the objects.
This cmdlet is similar to Export-Clixml except that Export-Clixml stores th
e resulting XML in a file. ConvertTo-XML returns the XML, so you can contin
ue to process it in Windows PowerShell.
PARAMETERS
-As
Determines the output format. Valid values are:
-- String: Returns a single string.
-- Stream: Returns an array of strings.
-- Document: Returns an XmlDocument object.
Stream is the default.
Required? false
Position? named
Default value Stream
Accept pipeline input? false
Accept wildcard characters? false
-Depth
Specifies how many levels of contained objects are included in the XML
representation. The default value is 1.
For example, if the object's properties also contain objects, to save a
n XML representation of the properties of the contained objects, you mu
st specify a depth of 2.
The default value can be overridden for the object type in the Types.ps
1xml files. For more information, see about_Types.ps1xml.
Required? false
Position? named
Default value 1
Accept pipeline input? false
Accept wildcard characters? false
-InputObject
Specifies the object to be converted. Enter a variable that contains th
e objects, or type a command or expression that gets the objects. You c
an also pipe objects to ConvertTo-XML.
Required? true
Position? 1
Default value None
Accept pipeline input? true (ByValue)
Accept wildcard characters? true
-NoTypeInformation []
Omits the Type attribute from the object nodes.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".
INPUTS
System.Management.Automation.PSObject
You can pipe any object to ConvertTo-XML.
OUTPUTS
System.String or System.Xml.XmlDocument
The value of the As parameter determines the type of object that Conver
tTo-XML returns.
NOTES
-------------------------- EXAMPLE 1 --------------------------
C:\PS>get-date | convertto-xml
Description
-----------
This command converts the current date (a DateTime object) to XML.
-------------------------- EXAMPLE 2 --------------------------
C:\PS>convertto-xml -as Document -inputObject (get-process) -depth 3
Description
-----------
This command converts the process objects that represent all of the process
es on the computer into an XML document. The objects are expanded to a dept
h of three levels.
RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=135204
Export-Clixml
Import-Clixml
ConvertTo-Html
ConvertTo-Csv
NAME
Convert-Path
SYNOPSIS
Converts a path from a Windows PowerShell path to a Windows PowerShell prov
ider path.
SYNTAX
Convert-Path [-LiteralPath] [-UseTransaction] []
Convert-Path [-Path] [-UseTransaction] []
DESCRIPTION
The Convert-Path cmdlet converts a path from a Windows PowerShell path to a
Windows PowerShell provider path.
PARAMETERS
-LiteralPath
Specifies the path to be converted. The value of the LiteralPath parame
ter is used exactly as it is typed. No characters are interpreted as wi
ldcards. If the path includes escape characters, enclose it in single q
uotation marks. Single quotation marks tell Windows PowerShell not to i
nterpret any characters as escape sequences.
Required? true
Position? 1
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
-Path
Specifies the Windows PowerShell path to be converted.
Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue, ByPropertyName)
Accept wildcard characters? false
-UseTransaction []
Includes the command in the active transaction. This parameter is valid
only when a transaction is in progress. For more information, see abou
t_Transactions.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".
INPUTS
System.String
You can pipe a path (but not a literal path) to Convert-Path.
OUTPUTS
System.String
Convert-Path returns a string that contains the converted path.
NOTES
The cmdlets that contain the Path noun (the Path cmdlets) manipulate pa
th names and return the names in a concise format that all Windows Powe
rShell providers can interpret. They are designed for use in programs a
nd scripts where you want to display all or part of a path name in a pa
rticular format. Use them like you would use Dirname, Normpath, Realpat
h, Join, or other path manipulators.
You can use the path cmdlets with several providers, including the File
System, Registry, and Certificate providers.
The Convert-Path cmdlet is designed to work with the data exposed by an
y provider. To list the providers available in your session, type "Get-
PSProvider". For more information, see about_Providers.
-------------------------- EXAMPLE 1 --------------------------
C:\PS>convert-path ~
Description
-----------
This command expands the current working directory.
-------------------------- EXAMPLE 2 --------------------------
C:\PS>convert-path HKLM:\software\microsoft
Description
-----------
This command converts the Windows PowerShell provider path to a standard re
gistry path.
RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113289
about_Providers
Test-Path
Split-Path
Resolve-Path
Join-Path
NAME
ConvertFrom-SecureString
SYNOPSIS
Converts a secure string into an encrypted standard string.
SYNTAX
ConvertFrom-SecureString [-Key ] [-SecureString] []
ConvertFrom-SecureString [[-SecureKey] ] [-SecureString] []
DESCRIPTION
The ConvertFrom-SecureString cmdlet converts a secure string (System.Securi
ty.SecureString) into an encrypted standard string (System.String). Unlike
a secure string, an encrypted standard string can be saved in a file for la
ter use. The encrypted standard string can be converted back to its secure
string format by using the ConvertTo-SecureString cmdlet. If an encryption
key is specified by using the Key or SecureKey parameters, the Rijndael enc
ryption algorithm is used. The specified key must have a length of 128, 192
, or 256 bits because those are the key lengths supported by the Rijndael e
ncryption algorithm. If no key is specified, the Windows Data Protection AP
I (DPAPI) is used to encrypt the standard string representation.
PARAMETERS
-Key
Specifies the encryption key as a byte array.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-SecureKey
Specifies the encryption key as a secure string. The secure string valu
e is converted to a byte array before being used as the key.
Required? false
Position? 2
Default value
Accept pipeline input? false
Accept wildcard characters? false
-SecureString
Specifies the secure string to convert to an encrypted standard string.
Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".
INPUTS
System.Security.SecureString
You can pipe a SecureString object to ConvertFrom-SecureString.
OUTPUTS
System.String
ConvertFrom-SecureString returns a standard string object.
NOTES
To create a secure string from characters that are typed at the command
prompt, use the AsSecureString parameter of the Read-Host cmdlet.
When you use the Key or SecureKey parameters to specify a key, the key
length must be correct. For example, a key of 128 bits can be specified
as a byte array of 16 digits. Similarly, 192-bit and 256-bit keys corr
espond to byte arrays of 24 and 32 digits, respectively.
-------------------------- EXAMPLE 1 --------------------------
C:\PS>$securestring = read-host -assecurestring
Description
-----------
This command creates a secure string from characters that you type at the c
ommand prompt. After entering the command, type the string you want to stor
e as a secure string. An asterisk (*) will be displayed to represent each c
haracter that you type.
-------------------------- EXAMPLE 2 --------------------------
C:\PS>$standardstring = convertfrom-securestring $securestring
Description
-----------
This command converts the secure string in the $securestring variable to an
encrypted standard string. The resulting encrypted standard string is stor
ed in the $standardstring variable.
-------------------------- EXAMPLE 3 --------------------------
C:\PS>$key = (3,4,2,3,56,34,254,222,1,1,2,23,42,54,33,233,1,34,2,7,6,5,35,4
3)
C:\PS> $standardstring = convertfrom-securestring $securestring -key $key
Description
-----------
These commands use the Rijndael algorithm to convert the secure string stor
ed in the $securestring variable to an encrypted standard string with a 192
-bit key. The resulting encrypted standard string is stored in the $standar
dstring variable.
The first command stores a key in the $key variable. The key is an array of
24 digits, all of which are less than 256.
Because each digit represents a byte (8 bits), the key has 24 digits for a
total of 192 bits (8 x 24). This is a valid key length for the Rijndael alg
orithm. Each individual value is less than 256, which is the maximum value
that can be stored in an unsigned byte.
The second command uses the key in the $key variable to convert the secure
string to an encrypted standard string.
RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113287
ConvertTo-SecureString
Read-Host
NAME
ConvertTo-SecureString
SYNOPSIS
Converts encrypted standard strings to secure strings. It can also convert
plain text to secure strings. It is used with ConvertFrom-SecureString and
Read-Host.
SYNTAX
ConvertTo-SecureString [-Key ] [-String] []
ConvertTo-SecureString [[-AsPlainText]] [[-Force]] [-String] []
ConvertTo-SecureString [[-SecureKey] ] [-String] []
DESCRIPTION
The ConvertTo-SecureString cmdlet converts encrypted standard strings into
secure strings. It can also convert plain text to secure strings. It is use
d with ConvertFrom-SecureString and Read-Host. The secure string created by
the cmdlet can be used with cmdlets or functions that require a parameter
of type SecureString. The secure string can be converted back to an encrypt
ed, standard string using the ConvertFrom-SecureString cmdlet. This enables
it to be stored in a file for later use.
If the standard string being converted was encrypted with ConvertFrom-Secur
eString using a specified key, that same key must be provided as the value
of the Key or SecureKey parameter of the ConvertTo-SecureString cmdlet.
PARAMETERS
-AsPlainText []
Specifies a plain text string to convert to a secure string. The secure
string cmdlets help protect confidential text. The text is encrypted
for privacy and is deleted from computer memory after it is used. If yo
u use this parameter to provide plain text as input, the system cannot
protect that input in this manner. To use this parameter, you must al
so specify the Force parameter.
Required? false
Position? 2
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Force []
Confirms that you understand the implications of using the AsPlainText
parameter and still want to use it.
Required? false
Position? 3
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Key
Specifies the encryption key to use when converting a secure string int
o an encrypted standard string. Valid key lengths are 16, 24, and 32 by
tes.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-SecureKey
Specifies the encryption key to use when converting a secure string int
o an encrypted standard string. The key must be provided in the format
of a secure string. The secure string is converted to a byte array befo
re being used as the key. Valid key lengths are 16, 24, and 32 bytes.
Required? false
Position? 2
Default value
Accept pipeline input? false
Accept wildcard characters? false
-String
Specifies the string to convert to a secure string.
Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".
INPUTS
System.String
You can pipe a standard encrypted string to ConvertTo-SecureString.
OUTPUTS
System.Security.SecureString
ConvertTo-SecureString returns a SecureString object.
NOTES
-------------------------- EXAMPLE 1 --------------------------
C:\PS>$secure = read-host -assecurestring
C:\PS> $secure
System.Security.SecureString
C:\PS> $encrypted = convertfrom-securestring -securestring $secure
C:\PS> $encrypted
01000000d08c9ddf0115d1118c7a00c04fc297eb010000001a114d45b8dd3f4aa11ad7c0abd
ae9800000000002000000000003660000a8000000100000005df63cea84bfb7d70bd6842e7
efa79820000000004800000a000000010000000f10cd0f4a99a8d5814d94e0687d7430b1000
00008bf11f1960158405b2779613e9352c6d14000000e6b7bf46a9d485ff211b9b2a2df3bd
6eb67aae41
C:\PS> $secure2 = convertto-securestring -string $encrypted
C:\PS> $secure2
System.Security.SecureString
Description
-----------
This example shows how to create a secure string from user input, convert t
he secure string to an encrypted standard string, and then convert the encr
ypted standard string back to a secure string.
The first command uses the AsSecureString parameter of the Read-Host cmdlet
to create a secure string. After you enter the command, any characters tha
t you type are converted into a secure string and then saved in the $secure
variable.
The second command displays the contents of the $secure variable. Because t
he $secure variable contains a secure string, Windows PowerShell displays o
nly the System.Security.SecureString type.
The third command uses the ConvertFrom-SecureString cmdlet to convert the s
ecure string in the $secure variable into an encrypted standard string. It
saves the result in the $encrypted variable. The fourth command displays th
e encrypted string in the value of the $encrypted variable.
The fifth command uses the ConvertTo-SecureString cmdlet to convert the enc
rypted standard string in the $encrypted variable back into a secure string
. It saves the result in the $secure2 variable. The sixth command displays
the value of the $secure2 variable. The SecureString type indicates that th
e command was successful.
-------------------------- EXAMPLE 2 --------------------------
C:\PS>$secure = read-host -assecurestring
C:\PS> $encrypted = convertfrom-securestring -secureString $secure -key (1.
.16)
C:\PS> $encrypted | set-content encrypted.txt
C:\PS> $secure2 = get-content encrypted.txt | convertto-securestring -key (
1..16)
Description
-----------
This example shows how to create a secure string from an encrypted standard
string that is saved in a file.
The first command uses the AsSecureString parameter of the Read-Host cmdlet
to create a secure string. After you enter the command, any characters tha
t you type are converted into a secure string and then saved in the $secure
variable.
The second command uses the ConvertFrom-SecureString cmdlet to convert the
secure string in the $secure variable into an encrypted standard string by
using the specified key. The contents are saved in the $encrypted variable.
The third command uses a pipeline operator (|) to send the value of the $en
crypted variable to the Set-Content cmdlet, which saves the value in the En
crypted.txt file.
The fourth command uses the Get-Content cmdlet to get the encrypted standar
d string in the Encrypted.txt file. The command uses a pipeline operator to
send the encrypted string to the ConvertTo-SecureString cmdlet, which conv
erts it to a secure string by using the specified key. The results are save
d in the $secure2 variable.
-------------------------- EXAMPLE 3 --------------------------
C:\PS>$secure_string_pwd = convertto-securestring "P@ssW0rD!" -asplaintext
-force
Description
-----------
This command converts the plain text string "P@ssW0rD!" into a secure strin
g and stores the result in the $secure_string_pwd variable. To use the AsPl
ainText parameter, the Force parameter must also be included in the command
.
RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113291
ConvertFrom-SecureString
Read-Host