As an experienced programmer, there will be many times when you’d want to write the output of your program to a file for troubleshooting, analysis, or for any other custom reason. In PowerShell, it is really easy to output any content to a file and in this article, we’ll see how you can do it. This is also a powerful tool for non-programmers or any IT pro who simply needs to output contents to a file for any number of reasons.
Using Out-File to send content to a file
Out-File is a PowerShell cmdlet that sends output to a file. For example, you can get the names of all processes and send it to a file for analysis and the code for that is:
Get-Process | Out-File C:\temp\process_list.txt
In this example, the Get-Process cmdlet gets all the processes running in the local system and sends it the file called “process_list.txt” in the C:\Temp directory using PowerShell’s pipeline. (You can change the file path to anything you want.) This code will create a new file called “process_list.txt” and will store the values in it.
Overwriting existing file
But what happens when you already have a file with the same name? This cmdlet will overwrite that file with a new one that contains the list of the current processes. If you don’t want your existing file to be overwritten, simply use a parameter called NoClobber. So, your code will be:
Get-Process | Out-File C:\temp\process_list.txt -NoClobber
When you execute this command, the cmdlet will display a message that the file already exists and will not overwrite it.
You also have the option to append values to an existing file using the Append parameter.
The Out-File cmdlet does not explicitly format objects and only writes whatever you pipe to it. However, if you send an unformatted object, Out-File sends that to a formatting cmdlet before writing it to the file, so the final output has a formatted object.
Also, it is worthwhile to note that Out-File does not give any object as its output. For example, when you pipe the output of this cmdlet to the Get-Member cmdlet, it will report that no object was received and this would prove that Out-File doesn’t output any object.
We saw FilePath and NoClobber earlier. Here are some of the other parameters you can use with this cmdlet.
- -FilePath: Allows you to specify the path of your file.
- -Append: Adds to an existing file instead of overwriting it.
- -Confirm: Asks you for confirmation before executing a cmdlet.
- -Encoding: You can choose the type of encoding for the target file. The default encoding is UTF8NoBOM and it can be changed to ASCII, OEM, Unicode, UTF7, UTF8, UTF32, and more.
- -Force: Overwrites an existing read-only file. But it is important to note that it does not override any security restrictions related to that file.
- -InputObject: Specifies the object that has to be written into the input file. This could be a variable that contains an object or a command/expression that fetches the object.
- -NoNewLine: This parameter tells your command not to include a new line character at the end of every line.
- -WhatIf: This is a simulation that shows what happens when a cmdlet is run, though, in reality, the cmdlet is not executed.
- -Width: Gives the option to decide how many characters you want in each line.
Thus, these are some of the parameters of Out-File.
Using Set-Content to send content to a file
Set-Content is another powerful cmdlet that greatly eases your job of writing content to a file in PowerShell.
This cmdlet overwrites the entire existing file with the contents you want. For example when you say:
Set-Content C:\temp\test.txt -Value ‘writing this content to a file in PowerShell’
This cmdlet will create a file called “test.txt” and will write the value to it. If that file already exists, it will simply overwrite it with this value. You can also use filters to write the text you want to a file.
Here are some of the common parameters of the Set-Content cmdlet.
- -Confirm: Checks with you before running the cmdlet.
- -Encoding: Specifies the encoding for the target file. The default is default and you can change it to ASCII, UTF7, UTF8, UTF32, OEM, string, Unicode, byte, and more.
- -Exclude: Allows you to explicitly mention the things that you don’t want in your target file. This parameter allows wildcard characters as well.
- -Filter: This is one of the most useful options in the Set-Content cmdlet and gives you complete control over the content.
- -Force: Forces the cmdlet to write the contents even if the target file is only a read-only file.
- -Include: Allows you to input a string or an array of strings or items into this cmdlet.
- -LiteralPath: Takes the path as it is and doesn’t interpret wildcards.
- -NoNewLine: Newline characters are not added at the end of each output.
- -Path: This takes the location of the file and wildcard characters are allowed.
- -Stream: Allows you to specify alternate streams for input and if the stream doesn’t exist, this cmdlet creates a new stream with that name.
- -Value: Specifies the content.
- -WhatIf: Simulates the command but doesn’t execute it.
Thus, these are options that come with the Set-Content cmdlet.
Now, let’s say you don’t want your cmdlet to overwrite the contents completely, but just want to add to the existing content. In that case, use the cmdlet Add-Content. Though both these cmdlets may sound similar, this one simply adds content to an existing file.
When to use Set-Content and Out-File?
So far, we have seen two ways to output content to a file and now, you might wonder which cmdlet to use and when?
A good rule of thumb is to use the Set-Content cmdlet when you want to get specific content from another file and input the same to a new file. To get specific content, use the cmdlet Get-Content and use Set-Content to write it.
On the other hand, if you want to write an object or an input that gets piped from another cmdlet, you can use the Out-File cmdlet.
Another difference is that Set-Content processes only strings whereas Out-File process objects as well.
Outputting contents to a file: Yes, it’s easy
To conclude, writing objects or content to a file is fairly common and you’d need it at some point in your programming. Regardless of how you use the output file, PowerShell makes it easy to input the contents you want to a file. The process is also fairly easy and doesn’t involve any cumbersome code that requires you to open or close a file. Rather, you can use one of the two cmdlets, Out-File or Set-Content, depending on your programming flow and requirements.
Do let us know which of the two you prefer and why.
More PowerShell Basics articles
- Neat trick: Organizing and formatting messy PowerShell output
- Adding help to your custom PowerShell cmdlets: Step-by-step guide
- Manage Microsoft Teams quickly and easily with PowerShell
- Building custom PowerShell cmdlets the easy way with modules
- Adding custom error messages to your PowerShell scripts