New-VHD

Module:

Hyper-V Module

Creates one or more new virtual hard disks.

Syntax

DynamicWithoutSource (Default)

New-VHD
    [-Path] <String[]>
    [-SizeBytes] <UInt64>
    [-Dynamic]
    [-BlockSizeBytes <UInt32>]
    [-LogicalSectorSizeBytes <UInt32>]
    [-PhysicalSectorSizeBytes <UInt32>]
    [-AsJob]
    [-CimSession <CimSession[]>]
    [-ComputerName <String[]>]
    [-Credential <PSCredential[]>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Differencing

New-VHD
    [-Path] <String[]>
    [-ParentPath] <String>
    [[-SizeBytes] <UInt64>]
    [-Differencing]
    [-BlockSizeBytes <UInt32>]
    [-PhysicalSectorSizeBytes <UInt32>]
    [-AsJob]
    [-CimSession <CimSession[]>]
    [-ComputerName <String[]>]
    [-Credential <PSCredential[]>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

FixedWithoutSource

New-VHD
    [-Path] <String[]>
    [-SizeBytes] <UInt64>
    [-Fixed]
    [-BlockSizeBytes <UInt32>]
    [-LogicalSectorSizeBytes <UInt32>]
    [-PhysicalSectorSizeBytes <UInt32>]
    [-AsJob]
    [-CimSession <CimSession[]>]
    [-ComputerName <String[]>]
    [-Credential <PSCredential[]>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

FixedWithSource

New-VHD
    [-Path] <String[]>
    -SourceDisk <UInt32>
    [-Fixed]
    [-BlockSizeBytes <UInt32>]
    [-AsJob]
    [-CimSession <CimSession[]>]
    [-ComputerName <String[]>]
    [-Credential <PSCredential[]>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

DynamicWithSource

New-VHD
    [-Path] <String[]>
    -SourceDisk <UInt32>
    [-Dynamic]
    [-BlockSizeBytes <UInt32>]
    [-AsJob]
    [-CimSession <CimSession[]>]
    [-ComputerName <String[]>]
    [-Credential <PSCredential[]>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Description

The New-VHD cmdlet creates one or more new virtual hard disks in either VHD format or the newer VHDX format. The file name extension you specify determines the format.

Examples

Example 1

PS C:\> New-VHD -Path c:\Base.vhdx -SizeBytes 10GB

This example creates a dynamic virtual hard disk in VHDX format that is 10 GB in size. The file name extension determines the format and the default type of dynamic is used because no type is specified.

Example 2

PS C:\> New-VHD -ParentPath c:\Base.vhdx -Path c:\Diff.vhdx -Differencing

This example creates a VHDX-format differencing virtual hard disk with a parent path of c:\Base.vhdx.

Example 3

PS C:\> New-VHD -Path C:\fixed.vhd -Fixed -SourceDisk 2 -SizeBytes 1TB

This example creates a 1 TB VHD-format fixed virtual hard disk at the specified path. The data for the virtual hard disk is populated from the disk identified in the system by the number 2. You can list the disks attached to the system and the number associated with each disk using the Get-Disk cmdlet.

Example 4

PS C:\> New-VHD -Path c:\LargeSectorBlockSize.vhdx -BlockSizeBytes 128MB -LogicalSectorSize 4KB -SizeBytes 1TB

This example creates a new 1 TB VHDX-format dynamic virtual hard disk at the specified path with a block size of 128 MB and a logical sector size of 4 KB.

Example 5

PS C:\> $vhdpath = "C:\VHDs\Test.vhdx"
PS C:\> $vhdsize = 127GB
PS C:\> New-VHD -Path $vhdpath -Dynamic -SizeBytes $vhdsize | Mount-VHD -Passthru |Initialize-Disk -Passthru |New-Partition -AssignDriveLetter -UseMaximumSize |Format-Volume -FileSystem NTFS -Confirm:$false -Force

This example creates a new 127GB VHD and then mounts, initializes, and formats it so the drive is ready to use.

Parameters

-AsJob

Runs the cmdlet as a background job.

Parameter properties

Type:	SwitchParameter
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

(All)

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-BlockSizeBytes

Specifies the block size, in bytes, of the virtual hard disk to be created.

Parameter properties

Type:	UInt32
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

(All)

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-CimSession

Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session object, such as the output of a New-CimSession or Get-CimSession cmdlet. The default is the current session on the local computer.

Parameter properties

Type:	CimSession[]
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

(All)

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-ComputerName

Specifies one or more Hyper-V hosts on which the virtual hard disk file(s) are to be created. NetBIOS names, IP addresses, and fully qualified domain names are allowable. The default is the local computer. Use localhost or a dot (.) to specify the local computer explicitly.

Parameter properties

Type:	String[]
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

(All)

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-Confirm

Prompts you for confirmation before running the cmdlet.

Parameter properties

Type:	SwitchParameter
Default value:	False
Supports wildcards:	False
DontShow:	False
Aliases:	cf

Parameter sets

(All)

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-Credential

Specifies one or more user accounts that have permission to perform this action. The default is the current user.

Parameter properties

Type:	PSCredential[]
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

(All)

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-Differencing

Specifies that a differencing virtual hard disk is to be created.

Parameter properties

Type:	SwitchParameter
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

Differencing

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-Dynamic

Specifies that a dynamic virtual hard disk is to be created.

Parameter properties

Type:	SwitchParameter
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

DynamicWithoutSource

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-Fixed

Specifies that a fixed virtual hard disk is to be created.

Parameter properties

Type:	SwitchParameter
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

FixedWithoutSource

Position:	Named
Mandatory:	True
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

FixedWithSource

Position:	Named
Mandatory:	True
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-LogicalSectorSizeBytes

Specifies the logical sector size, in bytes, of the virtual hard disk to be created. Valid values are 512 and 4096.

Parameter properties

Type:	UInt32
Default value:	None
Accepted values:	512, 4096
Supports wildcards:	False
DontShow:	False

Parameter sets

DynamicWithoutSource

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

FixedWithoutSource

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-ParentPath

Specifies the path to the parent of the differencing disk to be created (this parameter may be specified only for the creation of a differencing disk).

Parameter properties

Type:	String
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

Differencing

Position:	1
Mandatory:	True
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-Path

Path to the new virtual hard disk file(s) that is being created as a result of a command. If a filename or relative path is specified, the new virtual hard disk path is calculated relative to the current working directory.

Parameter properties

Type:	String[]
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

(All)

Position:	0
Mandatory:	True
Value from pipeline:	True
Value from pipeline by property name:	True
Value from remaining arguments:	False

-PhysicalSectorSizeBytes

Specifies the physical sector size, in bytes. Valid values are 512 and 4096.

Parameter properties

Type:	UInt32
Default value:	None
Accepted values:	512, 4096
Supports wildcards:	False
DontShow:	False

Parameter sets

DynamicWithoutSource

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

Differencing

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

FixedWithoutSource

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-SizeBytes

The maximum size, in bytes, of the virtual hard disk to be created.

Parameter properties

Type:	UInt64
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

DynamicWithoutSource

Position:	1
Mandatory:	True
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

FixedWithoutSource

Position:	1
Mandatory:	True
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-SourceDisk

Specifies the physical disk to be used as the source for the virtual hard disk to be created.

Parameter properties

Type:	UInt32
Default value:	None
Supports wildcards:	False
DontShow:	False
Aliases:	Number

Parameter sets

FixedWithSource

Position:	Named
Mandatory:	True
Value from pipeline:	False
Value from pipeline by property name:	True
Value from remaining arguments:	False

DynamicWithSource

Position:	Named
Mandatory:	True
Value from pipeline:	False
Value from pipeline by property name:	True
Value from remaining arguments:	False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Parameter properties

Type:	SwitchParameter
Default value:	False
Supports wildcards:	False
DontShow:	False
Aliases:	wi

Parameter sets

(All)

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Outputs

Microsoft.Vhd.PowerShell.VirtualHardDisk