Getting Started with DataCore Cmdlets

In this topic:

About DataCore Cmdlets


Operating Concepts


Also see:

DataCore Cmdlet Reference Guide for a complete list of cmdlets, syntax, descriptions, and examples.

DataCore Telemetry Cmdlets Reference Guide for a complete list of telemetry cmdlets, syntax, descriptions, and examples.

About DataCore Cmdlets

DataCore Software brings the features and functionality of SANsymphony™ Software-defined Storage platform to the Windows PowerShell™ command line interface.

DataCore Cmdlets for Windows PowerShell™ Support is installed as a component of SANsymphony software and has over 150 cmdlets so that administrators can manage SANsymphony software in a command line or scripting environment. This feature is supported for use with any DataCore Server running the same version of the software. The software component can also be installed on hosts or computers used for remote management running the DataCore Management Console.

After installation of the cmdlet component, a desktop shortcut is provided to open a Windows PowerShell™ command line interface to use when running the DataCore Cmdlets. When the shortcut is used to open a Windows PowerShell window, no additional configuration is necessary to run the cmdlets. In order to run from a window that is not opened from the shortcut, additional configuration will be required. See the Configuration section below for details.

The verb-noun cmdlet structure and syntax used in the cmdlets is consistent with the generic Windows PowerShell naming conventions and syntax. Each cmdlet name will consist of this format: Verb-DcsNoun. The “Dcs” in front of the noun identifies the cmdlet as a DataCore cmdlet. With few exceptions, most verbs used in cmdlet names are standard verbs. Most cmdlets return .NET Framework objects that can be used as input in other cmdlets. Errors from invoking cmdlets will appear in the window in red.

The entire list of DataCore Cmdlets can be displayed by invoking the cmdlet:

Get-Command –module DataCore.Executive.Cmdlets

The Cmdlet Help, with parameter descriptions and examples with output, can be displayed by invoking the standard Get-Help cmdlet with this syntax:

Get-Help <Cmdlet-Name> –full

In order to perform any actions using the cmdlets, a connection must first be made to a server using the Connect-DcsServer cmdlet. After the connection is made, the server can be used to manage any servers in the same server group.

See the Operation Concepts and Terminology sections below for important notes.


This documentation and use of the DataCore Cmdlets assumes that the audience consists of proficient Windows PowerShell™ command line interface users who are also proficient with the features and functions of SANsymphony software. Refer to Microsoft Windows documentation for more information on using Windows PowerShell.


If the DataCore Cmdlets are run from a PowerShell window opened through the installed shortcut, no additional configuration is necessary. The shortcut will automatically run the script Register-DcsCmdlets.ps1 from the installation folder. This script enables .NET 4.0 Command Language Runtime (CLR) support and imports the module DataCore.Executive.Cmdlets.dll. that is required to run the cmdlets. The script Register-DcsCmdlets.ps1 is provided as a way to make required configuration changes for the session without altering existing customer PowerShell profiles during our software installation. In this manner, only the window opened from the shortcut is configured to run the DataCore Cmdlets.

 If running the DataCore Cmdlets from a window that is not opened through the installed shortcut, the module must be imported. See Importing the DataCore.Executive.Cmdlets.dll Module for instructions.

In order to run other applications for Windows PowerShell (such as Windows PowerShell Integrated Shell Environment (ISE) or PowerGUI) with the DataCore Cmdlets, some configuration is required. See Configuring Applications for Windows PowerShell for instructions.

Also, if running a PowerShell script in a SANsymphony task, the script will run in a non-interactive default environment. Therefore, cmdlets that require user input or result in console output will not work. Some examples are write-host, read-host, and get-credential.

Importing the DataCore.Executive.Cmdlets.dll Module

The profile script named profile.ps1 can be used to import the module for the session. The profile script is a special script that runs every time a Windows PowerShell window is opened.
 The location of the file determines under what conditions the module will be imported.  


File Path

This profile applies to all users and all shells.


This profile applies to all users, but only to the Microsoft.PowerShell shell.

%windir%\system32\WindowsPowerShell\v1.0\ Microsoft.PowerShell_profile.ps1

This profile applies only to the current user, but affects all shells.

%UserProfile%\My Documents\WindowsPowerShell\profile.ps1

This profile applies only to the current user and the Microsoft.PowerShell shell.

%UserProfile%\My Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1

For more profile information, see

To import the module:

The profile script will get the installation path from the registry and import the module for the session.

1            Create a profile script named profile.ps1 and add the following commands.  

# Get the installation path of SANsymphonyV
$bpKey = 'BaseProductKey'
$regKey = Get-Item "HKLM:\Software\DataCore\Executive"
$strProductKey = $regKey.getValue($bpKey)
$regKey = Get-Item "HKLM:\$strProductKey"
$installPath = $regKey.getValue('InstallPath')

Import-Module "$installPath\DataCore.Executive.Cmdlets.dll" -DisableNameChecking -ErrorAction Stop

2           Select the desired usage from the table above and copy the file to the corresponding file path. For instance, if you want to import the module for all users and whenever a PowerShell window is opened, then the profile script should be copied to %windir%\system32\WindowsPowerShell\v1.0\profile.ps1.

Passing a Script Block

A script block can be passed to the script Register-DcsCmdlets.ps1 in order to pass a group of commands without following the configuration steps. The script block will be executed after the .NET 4.0 runtime session is enabled and our module is imported.

To pass a script block:

The following command line segment will pass a script block and keep the PowerShell window open:


$bpKey = 'BaseProductKey'

$regKey = Get-Item "HKLM:\Software\DataCore\Executive"

$strProductKey = $regKey.getValue($bpKey)

$regKey = Get-Item "HKLM:\$strProductKey"

$installPath = $regKey.getValue('InstallPath')


$scriptBlock = {

    $Server = $args[0]

    $Username = $args[1]

    $Password = $args[2]


    Connect-DcsServer -server $Server -username $Username -password $Password

    $connection = Get-DcsConnection

    Write-Host "Connected to <$connection>"

    Disconnect-DcsServer -connection $connection



& "$installPath\Register-DcsCmdlets.ps1" –ScriptBlock $scriptBlock –params "machine-name", "machine-username", "machine-password"


To exit the PowerShell window, replace the line above with this one:

& "$installPath\Register-DcsCmdlets.ps1" –ScriptBlock $scriptBlock –params " machine-name ", " machine-username ", " machine-password" –forceExit

Configuring Applications for Windows PowerShell

In order to work with DataCore Cmdlets, any other applications for Windows PowerShell, such as Windows PowerShell Integrated Shell Environment (ISE) or PowerGUI, must be configured to support .NET 4.0 runtime support. Configuration files are required for each executable file used by the application. The configuration files must contain the commands to enable .NET 4.0 runtime support and be named appropriately, as outlined below. The configuration files should reside in the installation folder for the software.

To configure .NET 4.0 runtime support:

1            Create or edit an existing config file with the following commands for each executable file used in the software:

<?xml version="1.0" encoding="utf-8" ?>
  <startup useLegacyV2RuntimeActivationPolicy="true">
        <supportedRuntime version="v4.0"/>
        <supportedRuntime version="v2.0.50727" />

2           The config file name should match the name of each executable file for the software with ".config" appended.
For example, if the software has two executable files named Console.exe and Editor.exe, then two configuration files named Console.exe.config and Editor.exe.config should exist in the installation folder for the software.  

Operation Concepts

Server Groups and Connections

The server group concept exists in the DataCore Cmdlets. In order to perform operations using the cmdlets, a connection must be made through a server to manage the associated server group (see Connect-DcsServer). When a connection is created using Connect-DcsServer, an alias will be assigned for that connection. The connection name (default or specified) will be used in every cmdlet.  

Default Server Group

Multiple connections to server groups are allowed to assist in management of multiple server groups. One connection can be designated as the default connection (see Set-DcsDefaultConnection). When a default connection is assigned using Set-DcsDefaultConnection, in most cmdlets the connection name is required and the default connection can be implied, rather than specifically used in the syntax.

Resolving Names Used in Cmdlets

When running cmdlets, names can be used to identify various objects. When a name is specified, the system attempts to resolve the name in an object by searching through the string fields of all objects of that type.

o           Server names - The server name must be unique or the name must be fully qualified. If more than one server exists with the same name specify the domain, for example

o           Physical disk names - In earlier versions, the default physical disk name was the index number which was unique to the server. As of the 9.0 release, the default name of a physical disk is the concatenation of the vendor and product name, which is not unique among multiple disks from the same product. A unique alias is not automatically generated. If a unique name is required for scripting purposes, then the name must be explicitly set using the cmdlet Set-DcsPhysicalDiskProperties. If physical disk names exist that not unique to the server group, the server name will be required to uniquely identify the physical disk.

o           Disk pool names - In earlier versions, disk pool names were unique to the DataCore Server. As of the 9.0 release, disk pool names are unique to the server group. If disk pool names exist that were created in earlier versions and are not unique to the server group, the server name will be required to uniquely identify the disk pool.

Additional Information

o           Date and time information used in the cmdlets is stored in data objects as UTC (Coordinated Universal Time). So a difference may be noticed between date and time parameter values used in cmdlets and what is displayed in date/time fields in returned objects.

o           When running the DataCore Cmdlet in a window other than the special Windows PowerShell window provided during the installation, the cmdlets must be registered (.\Register-DcsCmdlets.ps1). See the Configuration section in this topic.

o           Some Windows PowerShell "common parameters" may be supported in DataCore Cmdlet. Common parameters include Verbose, Debug, ErrorAction, ErrorVariable, WarningAction, WarningVariable, OutBuffer and OutVariable. These common parameters are Windows PowerShell parameters and are not documented in the SANsymphony Help. For more information, type, "get-help about_commonparameters" in a Windows PowerShell window.

o           Many cmdlets allow data objects to be piped in as parameter values. All cmdlets beginning with the verb Add return the created object, which can be piped to another cmdlet as input. Data objects can be obtained with the cmdlets beginning with the verb Get. For instance, the Serve-DcsVirtualDisk cmdlet can support the piped objects named VirtualDiskData to identify the virtual disks to serve. This object can be obtained by invoking Get-DcsVirtualDisk with the required parameters and pipe the returned objects directly into the cmdlet Serve-DcsVirtualDisk.

o           Pertaining to cmdlet Get-DcsPerformanceCounter, some raw data counters found in retrieved PerformanceData objects may not appear in the Performance tool in the management console. This is because some Performance tool counters are derived from these raw data counters.  Therefore, some raw data counters may not appear in the tool and some derived counters may not appear in retrieved PerformanceData objects. Special notes about these differences are documented in the description for Get-DcsPerformanceCounter.

o           All cmdlets beginning with the verb Set allow an empty string (" ") to be used as a parameter value in order to clear the setting.

o           The examples return performance counter data for the specified object. All times are stated in milliseconds (ms).


In order to remain consistent with underlying .NET Framework data objects used in the cmdlets, a few cmdlet names and associated Help descriptions will differ from similar terms used in the DataCore Management Console.

The following table bridges the slight differences in terminology between terms used in the DataCore Cmdlets and what is seen in the DataCore Management Console.

Cmdlet Term


Access token

(see Add-DcsAccessToken,


An access token is used to configure iSCSI target secrets for CHAP or mutual authentication. The term “access token” is not used in the DataCore Management Console.

Client or Client Host

(see Add-DcsClient)

Known as a host in the DataCore Management Console.


(see Get-DcsDistributionPlan, Start-DcsDistributionPlan)

Equivalent to the Evacuate and Redistribute operations used in Maintenance Mode.


(see Get-DcsObject)

An object or entity in the configuration that can be identified by an ID, such as a virtual disk, port, physical disk, pool and so on.

Logical disk

(see Add-DcsLogicalDisk,


A logical disk is the internal software representation of a virtual disk on a server. Logical disks are created by the software when virtual disks are created from disk pools or pass-through disks. A single virtual disk is comprised of one logical disk on one server. A mirrored or dual virtual disk is comprised of two logical disks—one logical disk on each server that was used as a storage source for the virtual disk.

Since logical disks are used internally by the software, they are not revealed in the DataCore Management Console, but are most closely related and referred to as "storage sources" in the console.


(see Get-DcsMonitor)

These are the system monitors used to gather resource information in the System Health tool in the DataCore Management Console.

Pool Member


Pool member is a term for the physical disks in a pool. The term is not used in the  DataCore Management Console.

Recording endpoint

(see Get-DcsRecordingEndpoint, Set-DcsRecordingEndpointProperties, Test-DcsRecordingEndpointConnection)

A recording endpoint is a server used for recording performance data, such as an SQL Server.

Recording point

(see Add-DcsRecordingPoint, Get-DcsRecordingPoint, Remove-DcsRecordingPoint)

A recording session is configured by adding categories, instances, and counters to the session. The recording session consists of a collection of recording points. Each recording point represents either a particular resource (instance) or an entire category of resources.


Note: Recording points must be retrieved or removed in the same manner as they were added. For instance, when "All instances" for a category has been added, the category must be removed. Categories are stored in the CategoryRecordingPointData object.  When individual instances or counters have been added, the instances must be removed. Instances are stored in the InstanceRecordingPointData object.


(see Add-DcsPoolDiskRelation)

Relation refers to the relationship between two physical disks that are mirrored in a pool or the two storage sources in a mirrored virtual disk.


(see Connect-DcsServer, Add-DcsServer)

Known as a DataCore Server in the DataCore Management Console.

Setting the server offline/online.

(see Set-DcsServerOffline,


When a server is set offline, the serving and mirroring capabilities of the server are disabled until the server is set online again. When offline, mirrored virtual disks with active paths using the server will failover and single virtual disks will be inaccessible to the client host

This is the same action as stopping/starting the DataCore Server in the DataCore Management Console.

Target Device

(see Get-DcsTargetDevice)

A target device defines the path connection between two ports.

Target Domain

(see Get-DcsTargetDomain)

A target domain defines the path connections between two machines.

Virtual logical unit

(see Add-DcsVirtualLogicalUnit, Get-DcsVirtualLogicalUnit,


Virtual logical unit is a front-end or mirror path of a logical disk on a server.