DSCResources/DSC_Disk/en-US/about_Disk.help.txt

.NAME
    Disk
 
.DESCRIPTION
    The resource is used to initialize, format and mount the partition/volume as a drive
    letter.
    The disk to add the partition/volume to is selected by specifying the DiskId and
    optionally DiskIdType.
    The DiskId value can be a Disk Number, Unique Id, Guid, Location, FriendlyName or SerialNumber.
 
    **Important: The Disk Number is not a reliable method of selecting a disk because
    it has been shown to change between reboots in some environments.
    It is recommended to use the Unique Id if possible.**
 
    The Disk Number, Unique Id, Guid, Location, FriendlyName and SerialNumber can be identified for a
    disk by using the PowerShell command:
 
    `powershell
    Get-Disk | Select-Object -Property FriendlyName,DiskNumber,UniqueId,Guid,Location,SerialNumber
    `
 
    Note: The Guid identifier method of specifying disks is only supported as an
    identifier for disks with GPT partition table format. If the disk is RAW
    (e.g. the disk has been initialized) then the Guid identifier method can not
    be used. This is because the Guid for a disk is only assigned once the partition
    table for the disk has been created.
 
    # Testing
    Note: Integration tests are not run for the Disk resource when SerialNumber
    is used since the virtual disk that is created does not have a serial number.
 
    ## Known Issues
 
    ### Defragsvc Conflict
 
    The 'defragsvc' service ('Optimize Drives') may cause the following errors when
    enabled with this resource. The following error may occur when testing the state
    of the resource:
 
    `text
    PartitionSupportedSize
    + CategoryInfo : NotSpecified: (StorageWMI:) [], CimException
    + FullyQualifiedErrorId : StorageWMI 4,Get-PartitionSupportedSize
    + PSComputerName : localhost
    `
 
    The 'defragsvc' service should be stopped and set to manual start up to prevent
    this error. Use the Service resource in either the 'xPSDesiredStateConfgiuration'
    or 'PSDSCResources' resource module to set the 'defragsvc' service is always
    stopped and set to manual start up.
 
    ### Null Location
 
    The Location for a disk may be null for some types of disk,
    e.g. file-based virtual disks. Physical disks or Virtual disks provided via a
    hypervisor or other hardware virtualization platform should not be affected.
 
    ### Maximum Supported Partition Size
 
    On some disks the maximum supported partition size may differ from the actual
    size of a partition created when specifying the maximum size. This difference
    in reported size is always less than 1MB, so if the reported _maximum supported
    partition size_ is less than 1MB then the partition will be considered to be
    in the correct state. This is a work around for https://windowsserver.uservoice.com/forums/301869-powershell/suggestions/36967870-get-partitionsupportedsize-and-msft-partition-clas
    that has been reported on user voice and also discussed in https://github.com/dsccommunity/StorageDsc/issues/181.
 
    ### ReFS on Windows Server 2019
 
    On Windows Server 2019 (build 17763 and above), Format-Volume throws an
    'Invalid Parameter' exception when called with ReFS as the FileSystem
    parameter. This results in an 'Invalid Parameter' exception being thrown
    in the Set in the 'Disk' resource.
    There is currently no known work around for this issue. It is being tracked
    in https://github.com/dsccommunity/StorageDsc/issues/227.
 
.PARAMETER DriveLetter
    Key - String
    Specifies the identifier for which disk to modify.
 
.PARAMETER DiskId
    Required - String
    Specifies the disk identifier for the disk to modify.
 
.PARAMETER DiskIdType
    Write - String
    Allowed values: Number, UniqueId, Guid, Location, FriendlyName, SerialNumber
    Specifies the identifier type the DiskId contains. Defaults to Number.
 
.PARAMETER PartitionStyle
    Write - String
    Allowed values: MBR, GPT
    Specifies the partition style of the disk. Defaults to GPT.
 
.PARAMETER Size
    Write - UInt64
    Specifies the size of new volume. Leave empty to use the remaining free space.
 
.PARAMETER FSLabel
    Write - String
    Define volume label if required.
 
.PARAMETER AllocationUnitSize
    Write - UInt32
    Specifies the allocation unit size to use when formatting the volume.
 
.PARAMETER FSFormat
    Write - String
    Allowed values: NTFS, ReFS
    Specifies the file system format of the new volume.
 
.PARAMETER AllowDestructive
    Write - Boolean
    Specifies if potentially destructive operations may occur.
 
.PARAMETER ClearDisk
    Write - Boolean
    Specifies if the disks partition schema should be removed entirely, even if data and OEM partitions are present. Only possible with AllowDestructive enabled.
 
.EXAMPLE 1
 
This configuration will wait for disk 2 to become available, and then make the disk available as
two new formatted volumes, 'G' and 'J', with 'J' using all available space after 'G' has been
created. It also creates a new ReFS formated volume on disk 3 attached as drive letter 'S'.
 
Configuration Disk_InitializeDataDisk
{
    Import-DSCResource -ModuleName StorageDsc
 
    Node localhost
    {
        WaitForDisk Disk2
        {
             DiskId = 2
             RetryIntervalSec = 60
             RetryCount = 60
        }
 
        Disk GVolume
        {
             DiskId = 2
             DriveLetter = 'G'
             Size = 10737418240
             DependsOn = '[WaitForDisk]Disk2'
        }
 
        Disk JVolume
        {
             DiskId = 2
             DriveLetter = 'J'
             FSLabel = 'Data'
             DependsOn = '[Disk]GVolume'
        }
 
        WaitForDisk Disk3
        {
             DiskId = 3
             RetryIntervalSec = 60
             RetryCount = 60
        }
 
        Disk SVolume
        {
             DiskId = 3
             DriveLetter = 'S'
             Size = 107374182400
             FSFormat = 'ReFS'
             AllocationUnitSize = 64KB
             DependsOn = '[WaitForDisk]Disk3'
        }
    }
}
 
.EXAMPLE 2
 
This configuration will wait for disk 2 with Unique Id '5E1E50A401000000001517FFFF0AEB84' to become
available, and then make the disk available as two new formatted volumes, 'G' and 'J', with 'J'
using all available space after 'G' has been created. It also creates a new ReFS formated
volume on disk 3 with Unique Id '5E1E50A4010000000029AB39450AC9A5' attached as drive letter 'S'.
 
Configuration Disk_InitializeDataDiskUsingUniqueId
{
    Import-DSCResource -ModuleName StorageDsc
 
    Node localhost
    {
        WaitForDisk Disk2
        {
             DiskId = '5E1E50A401000000001517FFFF0AEB84' # Disk 2
             DiskIdType = 'UniqueId'
             RetryIntervalSec = 60
             RetryCount = 60
        }
 
        Disk GVolume
        {
             DiskId = '5E1E50A401000000001517FFFF0AEB84' # Disk 2
             DiskIdType = 'UniqueId'
             DriveLetter = 'G'
             Size = 10GB
             DependsOn = '[WaitForDisk]Disk2'
        }
 
        Disk JVolume
        {
             DiskId = '5E1E50A401000000001517FFFF0AEB84' # Disk 2
             DiskIdType = 'UniqueId'
             DriveLetter = 'J'
             FSLabel = 'Data'
             DependsOn = '[Disk]GVolume'
        }
 
        WaitForDisk Disk3
        {
             DiskId = '5E1E50A4010000000029AB39450AC9A5' # Disk 3
             DiskIdType = 'UniqueId'
             RetryIntervalSec = 60
             RetryCount = 60
        }
 
        Disk SVolume
        {
             DiskId = '5E1E50A4010000000029AB39450AC9A5' # Disk 3
             DiskIdType = 'UniqueId'
             DriveLetter = 'S'
             Size = 100GB
             FSFormat = 'ReFS'
             AllocationUnitSize = 64KB
             DependsOn = '[WaitForDisk]Disk3'
        }
    }
}