What does the `-Sanitize` switch of the `Clear-Disk` cmdlet do in PowerShell? - 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?

Answer 1

[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?)