Sends output to a file.
Syntax
 Copy Code |
|
|---|---|
Out-File [-FilePath] <string> [[-Encoding] <string>] [-Append] [-Force] [-InputObject <psobject>] [-NoClobber] [-Width <int>] [-Confirm] [-WhatIf] [<CommonParameters>] |
|
Description
The Out-File cmdlet sends output to a file. You can use this cmdlet instead of the redirection operator (>) when you need to use its parameters.
Parameters
-Append
Adds the output to the end of an existing file, instead of replacing the file contents.
|
Required? |
false |
|
Position? |
named |
|
Default Value |
|
|
Accept Pipeline Input? |
false |
|
Accept Wildcard Characters? |
false |
-Encoding <string>
Specifies the type of character encoding used in the file. Valid values are "Unicode", "UTF7", "UTF8", "UTF32", "ASCII", "BigEndianUnicode", "Default", and "OEM". "Unicode" is the default.
"Default" uses the encoding of the system's current ANSI code page.
"OEM" uses the current original equipment manufacturer code page identifier for the operating system.
|
Required? |
false |
|
Position? |
2 |
|
Default Value |
|
|
Accept Pipeline Input? |
false |
|
Accept Wildcard Characters? |
false |
-FilePath <string>
Specifies the path to the output file. If the file does not exist in the specified path, Out-File creates the file, but it does not create directories.
|
Required? |
true |
|
Position? |
1 |
|
Default Value |
None |
|
Accept Pipeline Input? |
false |
|
Accept Wildcard Characters? |
false |
-Force
Allows the cmdlet to write (replace or append) to a read-only file.
The NoClobber parameter takes precedence over the Force parameter. If you use both parameters in a command, attempts to write to a read-only file fail.
|
Required? |
false |
|
Position? |
named |
|
Default Value |
|
|
Accept Pipeline Input? |
false |
|
Accept Wildcard Characters? |
false |
-InputObject <psobject>
Specifies the objects to be written to the file. The value can be an object, such as a quoted string, a variable that contains objects, or a command or expression that gets objects. You can also pipe objects to the Out-File cmdlet.
|
Required? |
false |
|
Position? |
named |
|
Default Value |
None |
|
Accept Pipeline Input? |
true (ByValue) |
|
Accept Wildcard Characters? |
false |
-NoClobber
Will not overwrite (replace the contents of) an existing file. By default, if the destination file has read-write attributes, Out-File overwrites the file without warning.
The NoClobber parameter takes precedence over the Force parameter, which lets you write to a read-only file. If you use both the Force and NoClobber parameters in a command, Out-File will not overwrite the file contents.
The NoClobber parameter does not prevent you from appending to a file. If both the Append and NoClobber parameters are used in a command, the output is appended to the file contents.
|
Required? |
false |
|
Position? |
named |
|
Default Value |
|
|
Accept Pipeline Input? |
false |
|
Accept Wildcard Characters? |
false |
-Width <int>
Specifies the number of characters in each line of output. Any additional characters are truncated, not wrapped. If you omit this parameter, the width is determined by the characteristics of the host. The default for the Windows PowerShell console is 80 (characters).
|
Required? |
false |
|
Position? |
named |
|
Default Value |
|
|
Accept Pipeline Input? |
false |
|
Accept Wildcard Characters? |
false |
-Confirm
Prompts you for confirmation before executing the command.
|
Required? |
false |
|
Position? |
named |
|
Default Value |
|
|
Accept Pipeline Input? |
false |
|
Accept Wildcard Characters? |
false |
-WhatIf
Describes what would happen if you executed the command without actually executing the command.
|
Required? |
false |
|
Position? |
named |
|
Default Value |
|
|
Accept Pipeline Input? |
false |
|
Accept Wildcard Characters? |
false |
<CommonParameters>
This command supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, and WarningVariable. For more information, see about_CommonParameters.
Inputs and Outputs
The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns.
|
Inputs |
System.Management.Automation.PSObject You can pipe any object to Out-File. |
|
Outputs |
None Out-File does not generate any output. |
Notes
The Out cmdlets do not format objects; they just render them and send them to the specified display destination. If you send an unformatted object to an Out cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it.
Out-File sends data, but it does not return any output objects. If you pipe the output of Out-File to Get-Member, Get-Member reports that no objects have been specified.
Example 1
| Copy Code |
|
|---|---|
C:\PS>get-process | out-file -filepath C:\Test\process.txt Description ----------- This command sends a list of processes on the computer to the Process.txt file. If the file does not exist in the Test directory, Out-File creates the file. However, if the Test1 directory does not exist, the command fails. Because the name of the FilePath parameter is optional, you can omit it and submit the equivalent command "get-process | outfile C:\Test\process.txt". |
|
Example 2
| Copy Code |
|
|---|---|
C:\PS>get-process | out-file C:\Test\process.txt -noclobber Out-File : File C:\Test\process.txt already exists and NoClobber was specified. At line:1 char:23 + get-process | out-file <<<< process.txt -noclobber Description ----------- This command also sends a list of processes to the Process.txt file, but it uses the NoClobber parameter, which prevents an existing file from being overwritten. The output shows the error message that appears when NoClobber is used with an existing file. |
|
Example 3
| Copy Code |
|
|---|---|
C:\PS>$a = get-process C:\PS> out-file -filepath C:\Test\process.txt -inputobject $a -encoding ASCII -width 50 Description ----------- These commands send a list of processes on the computer to the Process.txt file. The text is encoded in ASCII format so that it can be read by search programs like Findstr and Grep. By default, Out-File uses Unicode format. The first command gets the list of processes and stores them in the $a variable. The second command uses the Out-File cmdlet to send the list to the Process.txt file. The command uses the InputObject parameter to specify that the input is in the $a variable. It uses the Encoding parameter to convert the output to ASCII format. It uses the Width parameter to limit each line in the file to 50 characters. Because the lines of output are truncated at 50 characters, the rightmost column in the process table is omitted. |
|
Example 4
| Copy Code |
|
|---|---|
C:\PS>set-location hklm:\software c:\PS>get-acl mycompany\mykey | out-file -filepath c:\ps\acl.txt c:\PS>get-acl mycompany\mykey | out-file -filepath filesystem::acl.txt Description ----------- These commands show how to use the Out-File cmdlet when you are not in a FileSystem drive. The first command sets the current location to the HKLM:\Software registry key. The second and third commands have the same effect. They use the Get-Acl cmdlet to get the security descriptor of the MyKey registry subkey (HKLM\Software\MyCompany\MyKey). A pipeline operator passes the result to the Out-File cmdlet, which sends it to the Acl.txt file. Because Out-File is not supported by the Windows PowerShell Registry provider, you must specify either the file system drive name, such as "c:", or the name of the provider followed by two colons, "FileSystem::", in the value of the FilePath parameter. The second and third commands demonstrate these methods. |
|
Example 5
| Copy Code |
|
|---|---|
C:\PS>out-file -inputObject "Hello, World" -filepath C:\Test\read-only.txt -force Description ----------- This command writes the "Hello, World" string to the read-only.txt file. The Force parameter allows the Out-File cmdlet to write to the file, even if the has the read-only attribute. |
|