What does the `-Sanitize` switch of the `Clear-Disk` cmdlet do in PowerShell?

Question

The Clear-Disk cmdlet seems to have a currently undocumented -Sanitize switch:

PS> Get-Command Clear-Disk | Select-Object -ExpandProperty ParameterSets | ? {$_.Name -like 'ByName'} | Select-Object -ExpandProperty Parameters | ? {$_.Name -like 'Sanitize'}

Name                            : Sanitize
ParameterType                   : System.Management.Automation.SwitchParameter
IsMandatory                     : False
IsDynamic                       : False
Position                        : -2147483648
ValueFromPipeline               : False
ValueFromPipelineByPropertyName : False
ValueFromRemainingArguments     : False
HelpMessage                     :
Aliases                         : {}
Attributes                      : {InputObject (cdxml), ByNumber, ByPath, ByName...}

What does it do? Does it trigger the ATA/SCSI command SANITIZE?

Very odd. Just saw a GitHub issue opened in 2018 regarding this exact same question but, it was closed with a comment reading, that there's not association with the cmdlet. So it really wasn't answered? Lol it probably needs to be reopened — Abraham Zinala, Jan 08 '22 at 16:27
[Here](https://github.com/MicrosoftDocs/windows-powershell-docs/issues/327) it is. — Abraham Zinala, Jan 08 '22 at 18:37

TessellatingHeckler · Answer 1 · 2022-01-08T22:30:32.197

[Edit: this is incomplete; after all that it looks like Sanitize is its own separate, undocumented parameter]

There are a lot of cmdlets in PowerShell which were automatically generated wrappers around WMI. That mention of cdxml in your question is a giveaway that Clear-Disk is one of those.

Run Get-Command Clear-Disk | Format-List * and skim the results, it has:

OutputType: Microsoft.Management.Infrastructure.CimInstance#
                ROOT/Microsoft/Windows/Storage/MSFT_Disk

So Clear-Disk gives the MSFT_Disk WMI class a nice PowerShell cmdlet wrapper. MSFT_Disk is documented here. This seems to be out of date.

Clear-Disk is part of the Storage module, and that is in

C:\Windows\System32\WindowsPowerShell\v1.0\Modules\Storage>

In there is Disk.cdxml which is the mapping from WMI to Cmdlet, which contains:

<DefaultNoun>Disk</DefaultNoun>

[...]

<CmdletMetadata Verb="Clear" ConfirmImpact="High" />
    <Method MethodName="Clear">

NB. that PowerShell cmdlets are Verb-Noun, so this is the section for verb Clear on default noun disk to make Clear-Disk, and it maps to the method Clear() on the MSFT_Disk class, I think. Inside that section is:

      <Parameters>
        <!-- RemoveData -->
        <Parameter ParameterName="RemoveData">
          <Type PSType="System.Management.Automation.SwitchParameter" />
          <CmdletParameterMetadata />
        </Parameter>
        <!-- RemoveOEM -->
        <Parameter ParameterName="RemoveOEM">
          <Type PSType="System.Management.Automation.SwitchParameter" />
          <CmdletParameterMetadata />
        </Parameter>
        <!-- Sanitize -->
          <Parameter ParameterName="Sanitize">
          <Type PSType="System.Management.Automation.SwitchParameter" />
          <CmdletParameterMetadata />
        </Parameter>
        <!-- SourceCaller -->
        <Parameter ParameterName="cim:operationOption:SourceCaller" DefaultValue="Microsoft.PowerShell">
          <Type PSType="System.String" />
        </Parameter>
      </Parameters>
    </Method>

The MSFT_Disk documentation from earlier has a section documenting the Clear() Method.

That takes four parameters:

UInt32 Clear(
  [in]  Boolean RemoveData,
  [in]  Boolean RemoveOEM,
  [in]  Boolean ZeroOutEntireDisk,
  [out] String  ExtendedStatus
);

And the blob of XML seems to map those to PowerShell parameter names. I first thought these matched up and the ZeroOutEntireDisk was a rename of the third parameter, but that does not seem correct; Martin Smith has found a source which has both parameters mentioned.

ZeroOutEntireDisk [in] is documented as:

TRUE if this parameter instructs this method to zero out the entire disk in addition to removing all partition information. If this parameter is FALSE or NULL, only the first and last megabytes of the disk are zeroed.

C:\Windows\SysWOW64\wbem\en-GB\storagewmi.mfl describes Sanitize:

"If TRUE, this parameter instructs Clear to send command to the disk to physically obliterate data."

wbemtest is the WMI Tester, separate from PowerShell, and you can connect to the root\Microsoft\Windows\Storage namespace, Open Class the MSFT_Disk class, edit the Clear Method and get to the parameters there, and the MOF definition for the input parameters is:

[abstract]
class __PARAMETERS
{
    [In, ID(0): DisableOverride ToInstance] boolean RemoveData;
    [In, ID(1): DisableOverride ToInstance] boolean RemoveOEM;
    [In, ID(2): DisableOverride ToInstance] boolean ZeroOutEntireDisk;
    [In, ID(3): DisableOverride ToInstance] boolean Sanitize;
    [In, ID(4): DisableOverride ToInstance] boolean RunAsJob;
};

I don't know how the CDXML definition matches these. How it can call a method using fewer parameters than the method takes, whether it can match them in order or by name, what cim:operationOption:SourceCaller does, and whether this method even works or not (anyone tried?)

I started down this same rabbit hole but didn't realise the parameter had been renamed! — Martin Smith, Jan 08 '22 at 19:52
C:\Windows\SysWOW64\wbem\en-GB\storagewmi.mfl does contain both `ZeroOutEntireDisk` and `Sanitize` - not sure whether this is the mapping info. Trying to make sense of the format — Martin Smith, Jan 08 '22 at 20:06
It looks like they **are** different parameters. **Sanitize** is "If TRUE, this parameter instructs Clear to send command to the disk to physically obliterate data." **ZeroOutEntireDisk** is "If TRUE, this parameter instructs Clear to zero out the entire disk in addition to removing all partition information. If the parameter is FALSE or NULL, only the first and last megabyte of the disk is zeroed." — Martin Smith, Jan 08 '22 at 20:13
@MartinSmith oh that's interesting. What are `.mfl` files? Checking `$disk = gcim msft_disk -Namespace root/Microsoft/Windows/Storage |select -first 1` and then `$disk.CimClass.CimClassMethods['Clear'].Parameters` the base CIM class does have *both* Sanitize and ZeroOutEntireDisk parameters. The CDXML does not mention ZeroOutEntireDisk at all. I can't find much else on the internet or on Microsoft.com referencing these. — TessellatingHeckler, Jan 08 '22 at 21:39
I don't know. I was poking around in `C:\Windows\SysWOW64\wbem\storagewmi.mof` to see if the MOF file gave any clues and just searched that folder to see if any other files contain the string. Looks like some sort of localised documentation I assume. — Martin Smith, Jan 08 '22 at 22:25

What does the `-Sanitize` switch of the `Clear-Disk` cmdlet do in PowerShell?

1 Answers1