Utility.PS-Help.xml
|
<?xml version="1.0" encoding="utf-8"?>
<helpItems schema="maml"> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>ConvertFrom-SecureString</command:name> <command:verb>ConvertFrom</command:verb> <command:noun>SecureString</command:noun> <maml:description> <maml:para>Converts a secure string to an encrypted standard string.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `ConvertFrom-SecureString` cmdlet converts a secure string ( System.Security.SecureString ) into an encrypted standard string ( System.String ). Unlike a secure string, an encrypted standard string can be saved in a file for later use. The encrypted standard string can be converted back to its secure string format by using the `ConvertTo-SecureString` cmdlet.</maml:para> <maml:para>If an encryption key is specified by using the Key or SecureKey parameters, the Advanced Encryption Standard (AES) encryption 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 AES encryption algorithm. If no key is specified, the Windows Data Protection API (DPAPI) is used to encrypt the standard string representation.</maml:para> <maml:para>> [!NOTE] > Note that per DotNet (/dotnet/api/system.security.securestring?view=netcore-2.1#remarks), the > contents of a SecureString are not encrypted on non-Windows systems.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>ConvertFrom-SecureString</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"> <maml:name>SecureString</maml:name> <maml:description> <maml:para>Specifies the secure string to convert to an encrypted standard string.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.Security.SecureString</command:parameterValue> <dev:type> <maml:name>System.Security.SecureString</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AsPlainText</maml:name> <maml:description> <maml:para>When set, `ConvertFrom-SecureString` will convert secure strings to the decrypted plaintext string as output.</maml:para> <maml:para>This parameter was added in PowerShell 7.0.</maml:para> </maml:description> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>ConvertFrom-SecureString</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"> <maml:name>SecureString</maml:name> <maml:description> <maml:para>Specifies the secure string to convert to an encrypted standard string.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.Security.SecureString</command:parameterValue> <dev:type> <maml:name>System.Security.SecureString</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Key</maml:name> <maml:description> <maml:para>Specifies the encryption key as a byte array.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.Byte[]</command:parameterValue> <dev:type> <maml:name>System.Byte[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>ConvertFrom-SecureString</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"> <maml:name>SecureString</maml:name> <maml:description> <maml:para>Specifies the secure string to convert to an encrypted standard string.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.Security.SecureString</command:parameterValue> <dev:type> <maml:name>System.Security.SecureString</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>SecureKey</maml:name> <maml:description> <maml:para>Specifies the encryption key as a secure string. The secure string value is converted to a byte array before being used as the key.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.Security.SecureString</command:parameterValue> <dev:type> <maml:name>System.Security.SecureString</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AsPlainText</maml:name> <maml:description> <maml:para>When set, `ConvertFrom-SecureString` will convert secure strings to the decrypted plaintext string as output.</maml:para> <maml:para>This parameter was added in PowerShell 7.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.Management.Automation.SwitchParameter</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Key</maml:name> <maml:description> <maml:para>Specifies the encryption key as a byte array.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.Byte[]</command:parameterValue> <dev:type> <maml:name>System.Byte[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>SecureKey</maml:name> <maml:description> <maml:para>Specifies the encryption key as a secure string. The secure string value is converted to a byte array before being used as the key.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.Security.SecureString</command:parameterValue> <dev:type> <maml:name>System.Security.SecureString</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"> <maml:name>SecureString</maml:name> <maml:description> <maml:para>Specifies the secure string to convert to an encrypted standard string.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.Security.SecureString</command:parameterValue> <dev:type> <maml:name>System.Security.SecureString</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Security.SecureString</maml:name> </dev:type> <maml:description> <maml:para>You can pipe a SecureString object to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>This cmdlet returns the created plain text string.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>- 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 decimal numerals. Similarly, 192-bit and 256-bit keys correspond to byte arrays of 24 and 32 decimal numerals, respectively. - Some characters, such as emoticons, correspond to several code points in the string that contains them. Avoid using these characters because they may cause problems and misunderstandings when used in a password.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------- Example 1: Create a secure string --------------</maml:title> <dev:code>$SecureString = Read-Host -AsSecureString</dev:code> <dev:remarks> <maml:para>This command creates a secure string from characters that you type at the command prompt. After entering the command, type the string you want to store as a secure string. An asterisk (`*`) is displayed to represent each character that you type.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 2: Convert a secure string to an encrypted standard string</maml:title> <dev:code>$StandardString = ConvertFrom-SecureString $SecureString</dev:code> <dev:remarks> <maml:para>This command converts the secure string in the `$SecureString` variable to an encrypted standard string. The resulting encrypted standard string is stored in the `$StandardString` variable.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 3: Convert a secure string to an encrypted standard string with a 192-bit key</maml:title> <dev:code>$Key = (3,4,2,3,56,34,254,222,1,1,2,23,42,54,33,233,1,34,2,7,6,5,35,43) $StandardString = ConvertFrom-SecureString $SecureString -Key $Key</dev:code> <dev:remarks> <maml:para>These commands use the Advanced Encryption Standard (AES) algorithm to convert the secure string stored in the `$SecureString` variable to an encrypted standard string with a 192-bit key. The resulting encrypted standard string is stored in the `$StandardString` variable.</maml:para> <maml:para>The first command stores a key in the `$Key` variable. The key is an array of 24 decimal numerals, each of which must be less than 256 to fit within a single unsigned byte.</maml:para> <maml:para>Because each decimal numeral represents a single 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 AES algorithm.</maml:para> <maml:para>The second command uses the key in the `$Key` variable to convert the secure string to an encrypted standard string.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 4: Convert a secure string directly to a plaintext string</maml:title> <dev:code>$secureString = ConvertTo-SecureString -String 'Example' -AsPlainText $secureString # 'System.Security.SecureString' ConvertFrom-SecureString -SecureString $secureString -AsPlainText # 'Example'</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://learn.microsoft.com/powershell/module/microsoft.powershell.security/convertfrom-securestring?view=powershell-7.3&WT.mc_id=ps-gethelp</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertTo-SecureString</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Read-Host</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>ConvertTo-Csv</command:name> <command:verb>ConvertTo</command:verb> <command:noun>Csv</command:noun> <maml:description> <maml:para>Converts .NET objects into a series of character-separated value (CSV) strings.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `ConvertTo-CSV` cmdlet returns a series of character-separated value (CSV) strings that represent the objects that you submit. You can then use the `ConvertFrom-Csv` cmdlet to recreate objects from the CSV strings. The objects converted from CSV are string values of the original objects that contain property values and no methods.</maml:para> <maml:para>You can use the `Export-Csv` cmdlet to convert objects to CSV strings. `Export-CSV` is similar to `ConvertTo-CSV`, except that it saves the CSV strings to a file.</maml:para> <maml:para>The `ConvertTo-CSV` cmdlet has parameters to specify a delimiter other than a comma or use the current culture as the delimiter.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>ConvertTo-Csv</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects that are converted to CSV strings. Enter a variable that contains the objects or type a command or expression that gets the objects. You can also pipe objects to `ConvertTo-CSV`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.Management.Automation.PSObject</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Delimiter</maml:name> <maml:description> <maml:para>Specifies the delimiter to separate the property values in CSV strings. The default is a comma (`,`). Enter a character, such as a colon (`:`). To specify a semicolon (`;`) enclose it in single quotation marks.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.Char</command:parameterValue> <dev:type> <maml:name>System.Char</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>comma (,)</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="ITI"> <maml:name>IncludeTypeInformation</maml:name> <maml:description> <maml:para>When this parameter is used the first line of the output contains #TYPE followed by the fully qualified name of the object type. For example, #TYPE System.Diagnostics.Process .</maml:para> <maml:para>This parameter was introduced in PowerShell 6.0.</maml:para> </maml:description> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>#TYPE <Object></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="NTI"> <maml:name>NoTypeInformation</maml:name> <maml:description> <maml:para>Removes the #TYPE information header from the output. This parameter became the default in PowerShell 6.0 and is included for backwards compatibility.</maml:para> </maml:description> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="QF"> <maml:name>QuoteFields</maml:name> <maml:description> <maml:para>Specifies the names of the columns that should be quoted. When this parameter is used only the specified columns are quoted. This parameter was added in PowerShell 7.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.String[]</command:parameterValue> <dev:type> <maml:name>System.String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="UQ"> <maml:name>UseQuotes</maml:name> <maml:description> <maml:para>Specifies when quotes are used in the CSV files. Possible values are:</maml:para> <maml:para>- Never - don't quote anything</maml:para> <maml:para>- Always - quote everything (default behavior)</maml:para> <maml:para>- AsNeeded - only quote fields that contain a delimiter character, double-quote, or newline</maml:para> <maml:para> character</maml:para> <maml:para>This parameter was added in PowerShell 7.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Microsoft.PowerShell.Commands.BaseCsvWritingCommand+QuoteKind</command:parameterValue> <dev:type> <maml:name>Microsoft.PowerShell.Commands.BaseCsvWritingCommand+QuoteKind</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Always</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>ConvertTo-Csv</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects that are converted to CSV strings. Enter a variable that contains the objects or type a command or expression that gets the objects. You can also pipe objects to `ConvertTo-CSV`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.Management.Automation.PSObject</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="ITI"> <maml:name>IncludeTypeInformation</maml:name> <maml:description> <maml:para>When this parameter is used the first line of the output contains #TYPE followed by the fully qualified name of the object type. For example, #TYPE System.Diagnostics.Process .</maml:para> <maml:para>This parameter was introduced in PowerShell 6.0.</maml:para> </maml:description> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>#TYPE <Object></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="NTI"> <maml:name>NoTypeInformation</maml:name> <maml:description> <maml:para>Removes the #TYPE information header from the output. This parameter became the default in PowerShell 6.0 and is included for backwards compatibility.</maml:para> </maml:description> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="QF"> <maml:name>QuoteFields</maml:name> <maml:description> <maml:para>Specifies the names of the columns that should be quoted. When this parameter is used only the specified columns are quoted. This parameter was added in PowerShell 7.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.String[]</command:parameterValue> <dev:type> <maml:name>System.String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>UseCulture</maml:name> <maml:description> <maml:para>Uses the list separator for the current culture as the item delimiter. To find the list separator for a culture, use the following command: `(Get-Culture).TextInfo.ListSeparator`.</maml:para> </maml:description> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="UQ"> <maml:name>UseQuotes</maml:name> <maml:description> <maml:para>Specifies when quotes are used in the CSV files. Possible values are:</maml:para> <maml:para>- Never - don't quote anything</maml:para> <maml:para>- Always - quote everything (default behavior)</maml:para> <maml:para>- AsNeeded - only quote fields that contain a delimiter character, double-quote, or newline</maml:para> <maml:para> character</maml:para> <maml:para>This parameter was added in PowerShell 7.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Microsoft.PowerShell.Commands.BaseCsvWritingCommand+QuoteKind</command:parameterValue> <dev:type> <maml:name>Microsoft.PowerShell.Commands.BaseCsvWritingCommand+QuoteKind</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Always</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Delimiter</maml:name> <maml:description> <maml:para>Specifies the delimiter to separate the property values in CSV strings. The default is a comma (`,`). Enter a character, such as a colon (`:`). To specify a semicolon (`;`) enclose it in single quotation marks.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.Char</command:parameterValue> <dev:type> <maml:name>System.Char</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>comma (,)</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="ITI"> <maml:name>IncludeTypeInformation</maml:name> <maml:description> <maml:para>When this parameter is used the first line of the output contains #TYPE followed by the fully qualified name of the object type. For example, #TYPE System.Diagnostics.Process .</maml:para> <maml:para>This parameter was introduced in PowerShell 6.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.Management.Automation.SwitchParameter</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>#TYPE <Object></dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects that are converted to CSV strings. Enter a variable that contains the objects or type a command or expression that gets the objects. You can also pipe objects to `ConvertTo-CSV`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.Management.Automation.PSObject</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="NTI"> <maml:name>NoTypeInformation</maml:name> <maml:description> <maml:para>Removes the #TYPE information header from the output. This parameter became the default in PowerShell 6.0 and is included for backwards compatibility.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.Management.Automation.SwitchParameter</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="QF"> <maml:name>QuoteFields</maml:name> <maml:description> <maml:para>Specifies the names of the columns that should be quoted. When this parameter is used only the specified columns are quoted. This parameter was added in PowerShell 7.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.String[]</command:parameterValue> <dev:type> <maml:name>System.String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>UseCulture</maml:name> <maml:description> <maml:para>Uses the list separator for the current culture as the item delimiter. To find the list separator for a culture, use the following command: `(Get-Culture).TextInfo.ListSeparator`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.Management.Automation.SwitchParameter</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="UQ"> <maml:name>UseQuotes</maml:name> <maml:description> <maml:para>Specifies when quotes are used in the CSV files. Possible values are:</maml:para> <maml:para>- Never - don't quote anything</maml:para> <maml:para>- Always - quote everything (default behavior)</maml:para> <maml:para>- AsNeeded - only quote fields that contain a delimiter character, double-quote, or newline</maml:para> <maml:para> character</maml:para> <maml:para>This parameter was added in PowerShell 7.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Microsoft.PowerShell.Commands.BaseCsvWritingCommand+QuoteKind</command:parameterValue> <dev:type> <maml:name>Microsoft.PowerShell.Commands.BaseCsvWritingCommand+QuoteKind</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Always</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> </dev:type> <maml:description> <maml:para>You can pipe any object that has an Extended Type System (ETS) adapter to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>This cmdlet returns one or more strings representing each converted object.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>In CSV format, each object is represented by a character-separated list of its property value. The property values are converted to strings using the object's ToString() method. The strings are represented by the property value name. `ConvertTo-CSV` does not export the object's methods.</maml:para> <maml:para>The CSV strings are output as follows:</maml:para> <maml:para>- If IncludeTypeInformation is used, the first string consists of #TYPE followed by the object type's fully qualified name. For example, #TYPE System.Diagnostics.Process . - If IncludeTypeInformation is not used the first string includes the column headers. The headers contain the first object's property names as a character-separated list. - The remaining strings contain character-separated lists of each object's property values.</maml:para> <maml:para>Beginning with PowerShell 6.0 the default behavior of `ConvertTo-CSV` is to not include the #TYPE information in the CSV and NoTypeInformation is implied. IncludeTypeInformation can be used to include the #TYPE information and emulate the default behavior of `ConvertTo-CSV` prior to PowerShell 6.0.</maml:para> <maml:para>When you submit multiple objects to `ConvertTo-CSV`, `ConvertTo-CSV` orders the strings based on the properties of the first object that you submit. If the remaining objects do not have one of the specified properties, the property value of that object is Null, as represented by two consecutive commas. If the remaining objects have additional properties, those property values are ignored.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>------------- Example 1: Convert an object to CSV -------------</maml:title> <dev:code>Get-Process -Name pwsh | ConvertTo-Csv -NoTypeInformation "Name","SI","Handles","VM","WS","PM","NPM","Path","Parent","Company","CPU","FileVersion", ... "pwsh","8","950","2204001161216","100925440","59686912","67104", ...</dev:code> <dev:remarks> <maml:para>The `Get-Process` cmdlet gets the Process object and uses the Name parameter to specify the PowerShell process. The process object is sent down the pipeline to the `ConvertTo-CSV` cmdlet. The `ConvertTo-CSV` cmdlet converts the object to CSV strings. The NoTypeInformation parameter removes the #TYPE information header from the CSV output and is not required in PowerShell 6.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>--------- Example 2: Convert a DateTime object to CSV ---------</maml:title> <dev:code>$Date = Get-Date ConvertTo-Csv -InputObject $Date -Delimiter ';' -NoTypeInformation "DisplayHint";"DateTime";"Date";"Day";"DayOfWeek";"DayOfYear";"Hour";"Kind";"Millisecond";"Minute";"Month";"Second";"Ticks";"TimeOfDay";"Year" "DateTime";"Friday, January 4, 2019 14:40:51";"1/4/2019 00:00:00";"4";"Friday";"4";"14";"Local";"711";"40";"1";"51";"636822096517114991";"14:40:51.7114991";"2019"</dev:code> <dev:remarks> <maml:para>The `Get-Date` cmdlet gets the DateTime object and saves it in the `$Date` variable. The `ConvertTo-Csv` cmdlet converts the DateTime object to strings. The InputObject parameter uses the DateTime object stored in the `$Date` variable. The Delimiter parameter specifies a semicolon to separate the string values. The NoTypeInformation parameter removes the #TYPE information header from the CSV output and is not required in PowerShell 6.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------ Example 3: Convert the PowerShell event log to CSV ------</maml:title> <dev:code>(Get-Culture).TextInfo.ListSeparator Get-WinEvent -LogName 'PowerShellCore/Operational' | ConvertTo-Csv -UseCulture -NoTypeInformation , "Message","Id","Version","Qualifiers","Level","Task","Opcode","Keywords","RecordId", ... "Error Message = System error""4100","1",,"3","106","19","0","31716","PowerShellCore", ...</dev:code> <dev:remarks> <maml:para>The `Get-Culture` cmdlet uses the nested properties TextInfo and ListSeparator and displays the current culture's default list separator. The `Get-WinEvent` cmdlet gets the event log objects and uses the LogName parameter to specify the log file name. The event log objects are sent down the pipeline to the `ConvertTo-Csv` cmdlet. The `ConvertTo-Csv` cmdlet converts the event log objects to a series of CSV strings. The UseCulture parameter uses the current culture's default list separator as the delimiter. The NoTypeInformation parameter removes the #TYPE information header from the CSV output and is not required in PowerShell 6.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>--- Example 4: Convert to CSV with quotes around two columns ---</maml:title> <dev:code>Get-Date | ConvertTo-Csv -QuoteFields "DateTime","Date" DisplayHint,"DateTime","Date",Day,DayOfWeek,DayOfYear,Hour,Kind,Millisecond,Minute,Month,Second,Ticks,TimeOfDay,Year DateTime,"Thursday, August 22, 2019 11:27:34 AM","8/22/2019 12:00:00 AM",22,Thursday,234,11,Local,569,27,8,34,637020700545699784,11:27:34.5699784,2019</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>---- Example 5: Convert to CSV with quotes only when needed ----</maml:title> <dev:code>Get-Date | ConvertTo-Csv -UseQuotes AsNeeded DisplayHint,DateTime,Date,Day,DayOfWeek,DayOfYear,Hour,Kind,Millisecond,Minute,Month,Second,Ticks,TimeOfDay,Year DateTime,"Thursday, August 22, 2019 11:31:00 AM",8/22/2019 12:00:00 AM,22,Thursday,234,11,Local,713,31,8,0,637020702607132640,11:31:00.7132640,2019</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------------- Example 6: Convert hashtables to CSV -------------</maml:title> <dev:code>$person1 = @{ Name = 'John Smith' Number = 1 } $person2 = @{ Name = 'Jane Smith' Number = 2 } $allPeople = $person1, $person2 $allPeople | ConvertTo-Csv "Name","Number" "John Smith","1" "Jane Smith","2"</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 7: Converting hashtables to CSV with additional properties</maml:title> <dev:code>$allPeople | Add-Member -Name ExtraProp -Value 42 $allPeople | ConvertTo-Csv "Name","Number","ExtraProp" "John Smith","1","42" "Jane Smith","2","42"</dev:code> <dev:remarks> <maml:para>Each hashtable has a property named `ExtraProp` added by `Add-Member` and then converted to CSV. You can see `ExtraProp` is now a header in the output.</maml:para> <maml:para>If an added property has the same name as a key from the hashtable, the key takes precedence and only the key is converted to CSV.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/convertto-csv?view=powershell-7.3&WT.mc_id=ps-gethelp</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertFrom-Csv</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Export-Csv</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Import-Csv</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> </helpItems> |