Admin Power Level: Intermediate Chapter 15: Small Commands, Big Everyday Wins
Internet: get content from a web page
Invoke-WebRequest fetches a web page or a file over HTTP. It returns a response object with status, headers, and content, which you can inspect or save.
Lesson 1 of 5 in Chapter 15: Small Commands, Big Everyday Wins. Previous step in this path: Back up, restore, and refresh a GPO. 3 learning objectives, 6 examples, and a knowledge check.
Start: what you will learn
Invoke-WebRequest fetches a web page or a file over HTTP. It returns a response object with status, headers, and content, which you can inspect or save.
Learning objectives
- Fetch a page with Invoke-WebRequest
- Read status code and content from the response
- Save downloaded content to a file
Concept in simple words
What it is: Invoke-WebRequest fetches content from a web page or a file over HTTP, which is the protocol browsers use to ask a server for a page. If you have ever typed an address into a browser and waited for a page, you already know the job. The difference here is that PowerShell does the asking for you, so you can save the answer, check it, or pass it to another command, instead of only reading it on screen.
What problem it solves: a browser is built for a person to read one page at a time. PowerShell is built for repeatable work. You may need to download the same file on many computers, check whether a page is still up, read a small piece of data from a web service, or save a page for later reading. One command does that job, and it does it the same way every time, without clicking through menus.
What PowerShell does behind the command: when you run Invoke-WebRequest, PowerShell builds a request, sends it to the address in -Uri, waits for the server answer, and wraps that answer in a response object. By default the request is a GET request, which means: please send me this page, I am not sending you new data to store. The server then answers with a status code, a set of headers, and a body. Headers are small labels about the answer, such as what kind of content it is. The body is the page itself, held in the Content property as text.
The response object, piece by piece: StatusCode is a number, such as 200, and StatusDescription is the short text that goes with it, such as OK. Content holds the body as a string, which is plain text, even if that text happens to be HTML or JSON. Headers holds the header labels, so you can check the content type before you decide how to read the body. RawContent holds the full raw answer, and Links holds links found in an HTML page. The key idea is that you get an object with named parts, not one long blob of text, so you can pick exactly the part you need.
A very important behaviour to learn early: a failed request does not calmly return an object with 404 in it. When Invoke-WebRequest meets a non success answer, such as 404 or 500, it returns no output and throws a terminating error, which means the command stops with an error instead of giving you a result to inspect. That is why a simple pipe to Select-Object StatusCode will not show you 404 for a missing page. To catch that status code, you must wrap the request in a try and catch block, which is shown in a later example in this lesson. For a success, 200 is returned normally, and you can read StatusCode straight from the object.
Think of it like this
Think of it like this: ordering a book by post. You send the address, the shop sends the book back with a delivery note, and the note tells you whether the order succeeded. The status code is that delivery note, the content is the book itself, and -OutFile is asking for the book to be put straight on your shelf instead of handed to you to read on the spot. A failed order is different: instead of a book with a sad note inside, you get an error message at the door, and you must catch that message to learn the code, which is what try and catch does.
How it works, step by step
How it works, step by step, part one: First, choose the address carefully and check its spelling, because one wrong letter gives a 404 or a connection error. Write the full address, starting with https://, and put it in quotes, because an address with special characters can confuse PowerShell if it is not quoted. Second, ask yourself whether you trust the source, because a download is only safe to keep if it comes from a source you trust. Third, decide whether you want to look at the answer now, store it in a variable, or save it straight to a file.
How it works, step by step, part two: Run Invoke-WebRequest with -Uri and the address. If you stored the answer in a variable, check StatusCode first, before you try to read the content. If the code is 200, then read Content, or the one property you need. If you need a file, add -OutFile with a full path to a folder that already exists, because PowerShell will not create a missing folder for you. After a download, open the folder and check that the file is really there, and read a downloaded script or text file before you run anything from it.
Let us walk through the first example: take Invoke-WebRequest -Uri "https://example.com" | Select-Object StatusCode. -Uri names the address to fetch, and the pipe sends the response object to Select-Object. Select-Object keeps only the StatusCode property, so you do not have to scroll through a whole page. In the output, look for 200, which means the request succeeded. If this command ends in an error instead of a table, do not assume PowerShell is broken. Read the error, because it often means the address was wrong, the network did not reach the server, or the server answered with a failure code that threw an error.
Let us walk through the second example: take Invoke-WebRequest -Uri "https://example.com/file.txt" -OutFile "C:\Temp\file.txt". Here -OutFile tells PowerShell to save the body straight to a file, instead of printing it. The folder C:\Temp must already exist, or the download fails even though the web address was correct. Notice that this command prints no table on success, because the result went to disk, not to the screen. That silence is normal. Check the folder to confirm the file arrived. Warning: only download files on your own computer, with permission, and only from a source you trust, and read the file before you run anything from it.
Let us walk through the third example: take $page = Invoke-WebRequest -Uri "https://example.com" on the first line, then Write-Output $page.StatusCode on the second line. The first line fetches the page and stores the whole response object in a variable called $page, instead of printing it at once. The second line reads only the StatusCode property from that stored object, using dot notation, which means a dot followed by the property name. This pattern is handy because you can check the status first, and only then decide whether to read the content from the same stored response, without fetching the page a second time.
Let us walk through the fourth example: take $page = Invoke-WebRequest -Uri "https://example.com" on the first line, then Write-Output $page.StatusDescription on the second line. StatusDescription is the text partner of StatusCode, so for a success you should see OK next to the 200 you saw before. This is useful when a number alone feels unclear, because OK, Not Found, and similar short phrases explain the number in plain words. If you change the first line to a different address, the second line still works the same way, because it only reads one property from whatever response you stored.
Let us walk through the fifth example: take the try and catch block for a missing page. Inside try, Invoke-WebRequest runs with -ErrorAction Stop, which turns a failed request into a stopping error that catch can handle. Inside catch, the code reads $_.Exception.Response.StatusCode.value__, where $_ means the error that was just caught, and value__ holds the numeric code inside that error. In the output, look for 404, which means the page was not found at that address. If you remove -ErrorAction Stop, the catch block may not run in the way you expect, because the error may not stop the command in the same way, so keep that part exactly as shown when you practise this pattern.
Let us walk through the sixth example: take Invoke-WebRequest -Uri "https://example.com/file.txt" -OutFile "C:\Temp\file.txt" -PassThru | Select-Object StatusCode. -PassThru is the extra piece that changes the download behaviour: it saves the file and also returns the response object to the pipeline, instead of saving silently. The pipe then keeps only StatusCode, so you get both proof on disk and proof on screen. If you leave -PassThru out, you still get the file, but you get no status table, and that is expected, not a failure. Use -PassThru when you want to check the status in the same step as the download.
When to use it
When to use it, and when not to: use Invoke-WebRequest when you need to fetch a page, download a file, or read data from a web service, especially when that data is JSON text you can turn into objects with ConvertFrom-Json. Before you convert, check that the server really returned JSON, by looking at the content type in Headers and at the start of Content, because converting HTML as if it were JSON will fail. Do not use it to hammer a site with repeated requests, and do not assume a failed request means PowerShell is broken, because the address, the network, or the server is the more likely cause. Also, do not fetch content from an address you do not trust and run it without reading it first.
Edge cases to watch for: if an address has moved, PowerShell may follow a redirect to the new address, so the page you get back may come from the final address, not the one you typed. If an address is missing its https:// part, or has a space in it, the request may fail before it ever reaches the server, so copy the address exactly and keep it in quotes. If a page is very large, printing all of Content will flood your screen, so select one property, or save to a file with -OutFile, and then read the file in smaller pieces.
Worked examples
Read each example in order. Each one explains its parts, then shows what to look for in the output.
Syntax
Invoke-WebRequest -Uri <Url> [-OutFile <Path>]Example 1
Fetches a page and shows only its status code. 200 means the request succeeded. If the page is missing, this form throws an error instead of showing 404, so use the try and catch example for a missing page.
Invoke-WebRequest -Uri "https://example.com" | Select-Object StatusCodeIllustrative output: StatusCode ---------- 200
Example 2
Downloads a file and saves it, instead of printing its content. -OutFile names the file to create, and the folder in the path must already exist. Only download on your own computer, from a source you trust, and read the file before you run anything from it.
Invoke-WebRequest -Uri "https://example.com/file.txt" -OutFile "C:\Temp\file.txt"Illustrative output: File saved to C:\Temp\file.txt.
Example 3
The first line fetches the page and stores the whole response object in a variable called $page, instead of printing it at once. The second line reads only the StatusCode property from that stored object, using dot notation, which means a dot followed by the property name. This pattern is handy because you can check the status first, and only then decide whether to read the content from the same stored response.
$page = Invoke-WebRequest -Uri "https://example.com"
Write-Output $page.StatusCodeIllustrative output: 200
Example 4
The first line stores the whole response in $page, just like the previous example. The second line reads StatusDescription, which is the short text for the status code, such as OK for 200. Use this when a number alone is not clear enough, and keep the variable so you can also read Content or Headers from the same fetch.
$page = Invoke-WebRequest -Uri "https://example.com"
Write-Output $page.StatusDescriptionIllustrative output: OK
Example 5
The try block runs the request with -ErrorAction Stop, so a failed request becomes a stopping error. The catch block reads the numeric code from the caught error, where $_ means that error, and value__ holds its number. Use this pattern when you need to see 404 for a missing page, because a plain request throws an error instead of returning a status table.
try { Invoke-WebRequest -Uri "https://example.com/missing-page" -ErrorAction Stop } catch { $StatusCode = $_.Exception.Response.StatusCode.value__; Write-Output $StatusCode }Illustrative output: 404
Example 6
-OutFile saves the file, and -PassThru also returns the response object to the pipeline, instead of saving silently. Select-Object then keeps only StatusCode, so you get proof on disk and proof on screen in one step. Without -PassThru, the file still saves, but no status table is shown.
Invoke-WebRequest -Uri "https://example.com/file.txt" -OutFile "C:\Temp\file.txt" -PassThru | Select-Object StatusCodeIllustrative output: StatusCode ---------- 200
Nothing on this page executes PowerShell code. The outputs above are illustrative only.
Common mistakes and troubleshooting
Read these before you try the examples, so you can spot the same problems in your own work.
- Printing a whole page and trying to read it, when Select-Object StatusCode or Content would show the part you need.
- Assuming a failed request means PowerShell is broken. Check the URI, the network, and the status code first, and remember that a failure code such as 404 throws an error, so use try and catch to read it.
- Saving a download with -OutFile to a folder that does not exist yet, such as a Temp folder you assumed was there, so the download fails even though the web address was correct.
- Typing an address without https://, or without quotes, or with one wrong letter, and then blaming the command when the request never reaches the right server.
- Downloading a file from a source you do not trust and running it without reading it first. Always read a downloaded file before you run anything from it, and only download on your own computer with permission.
- Using -OutFile and expecting a status table back, then thinking the download failed because nothing printed. Without -PassThru, a successful download is silent, so check the folder, or add -PassThru when you want a status check too.
- Treating Content as if it were already an object, when it is really text. If the server returned JSON, pipe Content to ConvertFrom-Json first, and only then read properties with dot notation.
Knowledge check
Knowledge check
What does a status code of 200 mean?
Pick one answer. Feedback appears right away, and you can try again.
Remember this and next step
Remember this: status first, content second, save with -OutFile when you want a file, and use try and catch when you need the code from a failed request. A status code tells you quickly whether the request worked, a variable lets you reuse one fetch for many checks, and -PassThru gives you both a saved file and a status check in one step. Check the address, trust the source, and read before you run, and this small command will save you a lot of browser clicking.
Next step: Fine grained password policies (FGPP)