Skip to content

OpticalDiskDriveLetter

Jump to bottom
dscbot edited this page Jun 7, 2024 · 7 revisions

OpticalDiskDriveLetter

Parameters

Parameter Attribute DataType Description Allowed Values
DiskId Key String Specifies the optical disk number for the disk to assign the drive letter to.
DriveLetter Required String Specifies the drive letter to assign to the optical disk. Can be a single letter, optionally followed by a colon. This value is ignored if Ensure is set to Absent.
Ensure Write String Determines whether a drive letter should be assigned to the optical disk. Defaults to 'Present'. Present, Absent

Description

The resource is used to set the drive letter of an optical disk drive (e.g. a CDROM or DVD drive).

It can be used to set the drive letter of a specific optical disk drive if there are multiple in the system by specifying a value greater than 1 for the DiskId parameter.

In a system with a single optical disk drive then the DiskId should be set to 1.

In systems with multiple optical disks, the DiskId should be set to the ordinal number of the required optical disk found in the list returned when executing the following cmdlet:

Get-CimInstance -ClassName Win32_CDROMDrive

Warning: Adding and removing optical drive devices to a system may cause the order the optical drives appear in the system to change. Therefore, the drive ordinal number may be affected in these situations.

If the DiskId that is specified is greater than the number of manageable optical disk drives in the system, then the resource will write a warning to the log and will not attempt to set the drive letter. This will also occur if there are no manageable optical disk drives in the system.

If the DriveLetter that should be assigned to the optical disk drive is already assigned to another device, then the resource will throw an exception.

Detection of Manageable Optical Disk Drives

This resource is intended to manage permanent optical disk drives that are either physically present in the system or are presented to the system by hypervisors or other virtualization platforms. It is not intended to be used to manage temporary optical disk drives that are created when mounting ISOs on Windows Server 2012 and newer. Mounted ISO drives should be managed by the DSC_MountImage resource.

To detect whether a drive is a mounted ISO the following logic is used. For a CIM instance of a cimv2:Win32_CDROMDrive class representing an optical disk drive:

  1. Get the drive letter assigned to the drive in the cimv2:Win32_CDROMDrive. If the drive letter is set, query the volume information using the ``cimv2:Win32_Volume` CIM class for the device using drive letter and get the device path.
  2. If the drive letter is not set, then just create the device path from the drive property.
  3. Look up the disk image using the device path using the Get-DiskImage cmdlet.
  4. If no error occurs then the device is a mounted ISO and should not be used with this resource. If a "The specified disk is not a virtual disk." error occurs then it is not an ISO and can be managed by this resource.

Old Detection Method

Note: This method is no longer used because it is unreliable, but is documented here for reference.

In older versions (prior to v6.0.0) of the resource, the DSC_OpticalDiskDriveLetter resource used the DeviceID and the Caption of the CIM Instance representing the drive. This was not a 100% reliable method, and in recent versions of Windows Server, it was found that the DeviceID and Caption of the CIM Instance representing the drive were not unique enough to determine if the drive was a mounted ISO or not.

The following is a table of sample captions and device IDs for some common optical drive configurations. The items in bold are the strings used to determine if the drive is a mounted ISO.

Type Caption DeviceID Manage using
Mounted ISO in Windows Server 2019 Microsoft Virtual DVD-ROM SCSI\CDROM&VEN_MSFT&PROD_VIRTUAL_DVD-ROM\2&1F4ADFFE&0&000004 DSC_MountImage*
Physical device MATSHITA BD-MLT UJ260AF SCSI\CDROM&VEN_MATSHITA&PROD_BD-MLT_UJ260AF\4&23A5A6AC&0&000200 DSC_OpticalDiskDriveLetter
Hyper-V Gen1 (BIOS/IDE) VM - Windows Server 2019 Msft Virtual CD/ROM ATA Device IDE\CDROMMSFT_VIRTUAL_CD/ROM_____________________1.0_____\5&CFB56DE&0&1.0.0 DSC_OpticalDiskDriveLetter
Hyper-V Gen2 (UEFI/SCSI) VM - Windows Server 2019 Microsoft Virtual DVD-ROM SCSI\CDROM&VEN_MSFT&PROD_VIRTUAL_DVD-ROM\000001 DSC_OpticalDiskDriveLetter
Hyper-V Gen1 (BIOS/IDE) VM - Windows Server 2022 Msft Virtual CD/ROM ATA Device IDE\CDROMMSFT_VIRTUAL_CD/ROM_____________________1.0_____\5&CFB56DE&0&1.0.0 DSC_OpticalDiskDriveLetter
Hyper-V Gen2 (UEFI/SCSI) VM - Windows Server 2022 Microsoft Virtual DVD-ROM ... DSC_OpticalDiskDriveLetter
Azure Gen1 (BIOS/IDE) VM – Windows Server 2022 Azure Edition Msft Virtual CD/ROM ATA Device IDE\CDROMMSFT_VIRTUAL_CD/ROM_____________________1.0_____\5&CFB56DE&0&1.0.0 DSC_OpticalDiskDriveLetter
Azure Gen2 (UEFI/SCSI) VM – Windows Server 2022 Azure Edition Microsoft Virtual DVD-ROM SCSI\CDROM&VEN_MSFT&PROD_VIRTUAL_DVD-ROM\5&394B69D0&0&000002 DSC_pticalDiskDriveLetter

* Don't manage with this resource, use DSC_MountImage instead.

This is not a complete list, as some other virtual devices from other vendors might not be available for testing.

Known Issues

Some operating systems report the optical disk in the Win32_CDROMDrive list, but a volume that matches either the DeviceId or DriveLetter can not be found. The DriveLetter value appears as 'CdRom0' in the Win32_CDROMDrive list. This prevents the resource from matching the optical disk to a volume if the volume is not mounted.

This appears to only be an issue with IDE optical drives. SCSI optical drives do not appear to have this issue.

Therefore, this resource will not manage the optical disk if the volume can not be found and is not already mounted. The verbose logs will report this condition if detected. See Issue #289 for more information.

Examples

Example 1

This configuration will set the drive letter of the first optical disk drive in the system to 'Z'.

Configuration OpticalDiskDriveLetter_SetDriveLetter
{
    Import-DSCResource -ModuleName StorageDsc

    Node localhost
    {
        OpticalDiskDriveLetter SetFirstOpticalDiskDriveLetterToZ
        {
            DiskId      = 1
            DriveLetter = 'Z'
        }
    }
}

Example 2

This configuration will remove the drive letter of the first optical disk drive.

Configuration OpticalDiskDriveLetter_RemoveDriveLetter
{
    Import-DSCResource -ModuleName StorageDsc

    Node localhost
    {
        OpticalDiskDriveLetter RemoveFirstOpticalDiskDriveLetter
        {
            DiskId      = 1
            DriveLetter = 'X' # This value is ignored
            Ensure      = 'Absent'
        }
    }
}

Example 3

This configuration will set the drive letter of the first optical disk drive in the system to 'Y'. It will set the drive letter of the second optical disk drive to 'Z'. It will remove the drive letter from the third optical disk drive in the system.

Configuration OpticalDiskDriveLetter_SetDriveLetterMulti
{
    Import-DSCResource -ModuleName StorageDsc

    Node localhost
    {
        OpticalDiskDriveLetter SetFirstOpticalDiskDriveLetterToY
        {
            DiskId      = 1
            DriveLetter = 'Y'
        }

        OpticalDiskDriveLetter SetSecondOpticalDiskDriveLetterToZ
        {
            DiskId      = 2
            DriveLetter = 'Z'
        }

        OpticalDiskDriveLetter RemoveThirdOpticalDiskDriveLetter
        {
            DiskId      = 3
            DriveLetter = 'A'
            Ensure      = 'Absent'
        }
    }
}

Home

General

Clone this wiki locally