The first Out cmdlet we're going to explore is a pretty popular one,
which is Out‑File.
The name of this cmdlet is pretty self‑explanatory,
but let's check out the help by running help Out‑File.
The synopsis is straightforward enough.
It sends output to a file.
Something of interest here is that it doesn't say what
type of file you need to specify.
And that's because Out‑File is dealing with text,
and it will output to a file with whatever extension you give it.
But in our demo, we're going to work with a plain old text file.
Let's keep using the example from the last module of working with Get‑Process.
And I'm going to just choose processes starting with an s so we
don't have a lot of data to scroll around with.
We can simply pipe that across to Out‑File,
which has a parameter named ‑FilePath,
which is where you need to tell PowerShell where you
want the data to be output to.
I'll store it in C:\Docs\ and call the file process.txt.
I could show this to you in the console with Get‑Content,
but I want to open this up in Notepad just so you can visualize what's going on.
So I'll run notepad C:\Docs\process.txt.
Let me make that bigger, and there are a couple of things to point out here.
Firstly, this is just a raw text file.
These are no longer PowerShell objects.
I can't import this back in and suddenly have PowerShell
objects at my disposal to work with.
Secondly, I didn't specify a format command,
so PowerShell has used the default formatting for Get‑Process,
which is to output the results to a table with these specific properties.
With that said,
you can override the formatting before you output the data to a file.
So if I run Get‑Process s*, I can pipe that across to,
say, Format‑List and then pipe that down to Out‑File.
The ‑FilePath parameter is positional, so I don't need to specify the parameter,
and I can just type the path of the file.
And I'll use the same one, being C:\Docs\process.txt.
I'll up arrow to get the Notepad command again.
And this time you can see we've got the list format in the external text file.
Notice that I used the same file name,
and it didn't ask me if I want to overwrite the file.
That's the default behavior.
And if you want to stop that from happening,
you can use this ‑NoClobber parameter to prevent an
existing file from being overwritten.
And we'll get an error to say that this file already exists.
Out‑File has an ‑Append parameter.
So notice I've taken the Format‑List command out of the pipeline,
but I'm using the ‑Append parameter.
I'll open up the file again in Notepad,
and we've got our original list format from a few commands ago.
And if I scroll down towards the bottom here,
we'll see the table output has been appended to the
same file from the cmdlet I just ran.
The parameter named ‑NoNewLine will ensure the content written to
the file doesn't end with a new line character.
The string representations of the object being specified
are concatenated to form the output.
Notepad is doing a bit of wrapping here,
but this entire output is actually on a single line.
Another parameter is named ‑Width,
which is where you can tell PowerShell how many characters
should be present on each line of the output.
Any additional characters are truncated; they aren't wrapped.
Let's set that width to 20 and then open the file in Notepad.
And we've only got the first 20 characters of each line in the default output.
The Out cmdlets all have a parameter named ‑InputObject,
so in the examples above, the data was being piped to Out‑File,
but you can use the ‑InputObject parameter and specify the data to be output.
So let's create a variable named process,
and we'll use that to store the processes starting with s.
You can then just call Out‑File on its own and use the
‑InputObject parameter to specify the variable where the
objects are stored that you want to output,
and then specify the ‑FilePath for the file to output to.
If we check that with Notepad, functionally,
this is the same as piping the data to Out‑File.
But it's just another way of specifying the data to be output.
In the previous clip,
I mentioned that you can't pipe Out cmdlets to another cmdlet because
Out cmdlets remove the objects from the pipeline,
and they send the data out of the PowerShell system.
Out‑File saves the data to a file,
but it does not produce any output objects to the pipeline.
Let me get the processes starting with s again and pop that across to Out‑File.
And then we can pipe that down to Get‑Member.
Get‑Member errors out here,
telling us that we must specify an object for the Get‑Member cmdlet.
So this shows that nothing is being sent down the pipeline from Out‑File.
There's something else I want to cover here briefly,
and it isn't specifically related to Out‑File,
but it is related to getting output from PowerShell to text files.
And you might be familiar with this from command.exe days.
And that is using the redirection operators to get
data from PowerShell out to a file.
I want to show you the help file named about_redirection,
and there are a couple of things I'd like to highlight in here.
As we've learned, by default, PowerShell sends its output to the console,
but we can direct the output to a text file instead.
There are these things called streams, which we'll see more about in a moment.
But, interestingly,
you can also redirect the error output to the regular output stream.
And over here, it lists a few ways to redirect output,
the first being to use Out‑File, which is what we've worked through here.
And in this help document,
they note that you'd typically use Out‑File when you want to use its parameters.
There's another cmdlet named Tee‑Object.
And, lastly, you can use these things called redirection operators.
If I press space to page on to the next screen in the help document,
we get some information about the redirection operators.
I'm not going to go through all of this with you.
You're obviously welcome to do that in your own time.
But a couple of things to highlight here are in the middle,
and these are all of the output streams available in
PowerShell to output different types of data.
And the default stream, if you don't specify one,
is Stream #1, the SUCCESS Stream.
At the very bottom, it starts to tell us what the redirection operators are,
and this first one that's on screen, you may be familiar with,
which is the greater‑than sign.
And that sends the specified stream to a file.
I'll page down here just once more, and at the very top,
there's another operator, which is two greater‑than signs,
which will append the specified stream to a file.
And this last syntax here allows you to redirect one of
the other streams to the success stream.
Let's do a quick example of that in the console.
If we run Get‑Process again,
we can just then use the greater‑than symbol as the redirection operator
and then specify the name of the file to output to.
I'll fire that up in Notepad.
And, sure enough,
we get the same output that we were getting with Out‑File
because it's effectively doing the same thing.
Back in the console, if we bring up that same command,
but I'll go back to add another greater‑than symbol,
this is telling PowerShell to append the data to the file.
So this is exactly the same as using Out‑File with the ‑Append parameter.
Depending on what you're doing in the shell,
you might find yourself using the redirection operator,
but Out‑File definitely can be useful if you need some extra controls around the output.