What does the -raw switch parameter in Get-Content really do in Powershell? Finding helpful documentation

Question

I've been trying to work with an API that only accepts raw text or base64 encoded values in a JSON object. The content I'm POSTing is data from an XML file. So I used Powershell's Get-Content cmdlet (without -Raw) to retrieve the data from the .xml and then base64 encode it and sent it to the API. The API then decodes it, but the XML formatting was lost.

I found a SO post about using the -Raw switch on Get-Content, but it seems like the documentation for this switch is vague. When I used the -Raw switch, encoded it and sent it back to the API, the formatting was good.

Answer 1

As per Kory Gill's comment and your own, the built-in Get-Help and MSDN documentation should be your first port of call. But you've already RTFM!

When that fails, ss64 is great reference for Powershell documentation and additional examples.

Get-Content page here. It has this to say about -Raw:

Return multiple lines as a single string (PowerShell 3.0)
In PowerShell 2.0 use the static method: [System.IO.File]::ReadAllText(string path)

Answer 2

briantist's helpful comment on the question sums up the answer succinctly (in his words; lightly edited, emphasis added):

Get-Content [by default] reads a file line by line and returns an array of the lines. Using -Raw reads the entire contents of the file as a single string.

The name -Raw is tad unfortunate, because it mistakenly suggests reading raw bytes, whereas -Raw still detects encodings and ultimately reads everything into a .NET [string] type.
(By contrast, you need either -Encoding Byte (Windows PowerShell) or -AsByteStream (PowerShell Core) to read a file as a byte array.)

Given -Raw's actual purpose, perhaps something like -Whole would have been a better name, but that ship has sailed (though adding an alias name for a parameter is still an option).

Let's take a look at why this information may currently be difficult to discover [Update: It no longer is]:

---

[Update: This section is now OBSOLETE, except the link to the PowerShell documentation GitHub repository, which welcomes contributions, bug reports, suggestions]

A Tale of PowerShell Documentation Woes

The central conflict of this tale is the tension between the solid foundation of PowerShell's potentially great help system and its shoddy current content.

• As is often the case, third parties come to the rescue, as shown in gms0ulman's helpful answer.

• As briantist also points out, however, PowerShell's documentation is now open-source and welcomes contributions; he states:
  "I will direct your attention to the Edit link [for the Get-Content help topic on GitHub] [...] so you can actually fix it up and submit something better (including examples). I have done it before; they do accept pull requests for it."
  The caveat is that while future PowerShell Core versions will benefit from improvements, it's not clear whether improvements will make their way back into Windows PowerShell.

Let's ask PowerShell's built-in help system, accessible via the standard Get-Help cmdlet (the content for which may not be preinstalled; install when prompted, or run Update-Help from an elevated session):

Get-Help Get-Content -Parameter Raw

Note how you can conveniently ask for help on a specific parameter (-Parameter Raw).

On Windows PowerShell v5.1, this yields:

-Raw 
  Ignores newline characters and returns the entire contents of a file in one string.  
  By default, the contents of a file is returned as a array of strings that is delimited  
  by the newline character.
        
  Raw is a dynamic parameter that the FileSystem provider adds to the Get-Content cmdlet.  
  This parameter works only in file system drives.
        
  This parameter is introduced in Windows PowerShell 3.0.

  Required?                    false
  Position?                    named
  Default value
  Accept pipeline input?       false
  Accept wildcard characters?  false

That is indeed what we were looking for and quite helpful (leaving the awkward phrasing "delimited by the newline character" aside and that on Windows a newline is a character sequence).

On Powershell Core v6.0.2, this yields:

-Raw
    
    Required?                    false
    Position?                    Named
    Accept pipeline input?       false
    Parameter set name           (All)
    Aliases                      None
    Dynamic?                     true

While the meta-data is more detailed - including a hint that the parameter is dynamic (see below) - it is crucially missing a description of the parameter.

Some provider-cmdlet parameters are dynamic, in that they are specific to a given provider, so there is a mechanism to specify the target provider when asking for help, by passing a provider-specific example path to the -Path parameter.

In the case at hand, let's therefore try (PowerShell Core on Windows):

Get-Help Get-Content -Parameter Raw -Path C:\

Sadly, the result is the same unhelpful response as before.

Note that, as long as you're invoking the command from a filesystem location, explicit use of -Path should not be necessary, because the provider underlying the current location is implicitly targeted.

---

Now let's take a look at the online versions of PowerShell's help topics:

As it turns out, a given provider cmdlet can have multiple documentation pages:

• A generic one that applies to all providers.

• Provider-specific pages that document provider-exclusive behavior and parameters, such as -Raw for the filesystem provider.

Sadly, the generic topics make no mention of the existence of the provider-specific ones, making them hard to discover.

• Googling Get-Content takes you to https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/get-content, the generic topic, which contains the following misleading statement: This parameter is not supported by any providers that are installed with Windows PowerShell.

  • This is not only unhelpful, but actively misleading, because the PowerShell file-system provider clearly is installed with PowerShell and it does support -Raw.
    [Drive] providers are PowerShell's generalization of the filesystem drive metaphor to support targeting other [typically hierarchical] storage systems with a unified set of cmdlets. For instance, Windows PowerShell also ships with the registry drive provider, which allows managing the registry as if it were a drive.

• The -Online switch for Get-Help conveniently allows opening the online version of the requested topic in the browser; so let's try that (Get-Help Get-Content -Online):

  • Windows PowerShell v5.1: Takes you a 404 page(!) related to v4.

  • PowerShell Core v6.0.1: Takes you to the same generic topic that googling does.

There's a sliver of hope, however: The aforementioned 404 page offers a link to the filesystem-provider-specific topic: Get-Content for FileSystem

It is there that we finally discover the online version of the truly relevant, provider-specific information, which is the same that Get-Help Get-Content -Parameter Raw provides locally, but - as stated - only in Windows PowerShell.