Getting Started with DataCore Cmdlets

In this topic:

About DataCore Cmdlets

Configuration

Operating Concepts

Terminology

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.

Configuration

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.  

For more profile information, see http://msdn.microsoft.com/en-us/library/windows/desktop/bb613488%28v=vs.85%29.aspx.

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" ?>
<configuration>
  <startup useLegacyV2RuntimeActivationPolicy="true">
        <supportedRuntime version="v4.0"/>
        <supportedRuntime version="v2.0.50727" />
    </startup>
</configuration>

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 Server1.mydomain.com.

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).

Terminology

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.