Developer Documentation
Citrix Daas SDK

Get-EnvTestDBVersionChangeScript

August 9, 2024
Contributed by: 
C C

Gets an SQL service schema update script for the Citrix EnvTest Service.

Syntax

Get-EnvTestDBVersionChangeScript
   -DatabaseName <String>
   -TargetVersion <Version>
   [-AzureDatabase]
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->

Description

Gets an SQL script that can be used to update the current Citrix EnvTest Service database schema. An update can be an upgrade or downgrade.

A script can be obtained to update the current service schema to any version that is reachable by applying available schema update packages that have been uploaded by the Citrix EnvTest Service.

Typically, this mechanism is used to update the current service schema to a newer version, however it can also be used to revert previously applied updates.

The SQL script obtained can be run using SQL Server’s SQLCMD utility, or by copying the script into an SQL Server Management Studio (SSMS) query window and executing the query. If using SSMS, the query must be executed in ‘SQLCMD mode’.

The schema update packages used to generate update scripts are stored in the database; because of this, any Citrix EnvTest Service in the site can be used to obtain a schema update script.

The fact that an update package is available in the database does not mean that the update has actually been applied to the service’s schema. In addition, application of an update does not remove the associated update packages.

Take care when using the update scripts. Citrix recommends that where possible service schema upgrades are performed using Studio rather than manually via the SDK. The database should be backed-up before an update is attempted. The database script may also require exclusive use of the schema, in which case all Citrix EnvTest Services must be shutdown before applying the update.

Once an update has been applied to the service schema, any existing Citrix EnvTest Services that are incompatible with the updated schema will cease to operate. The service state, as reported by Get-EnvTestServiceStatus, provides information about the service compatibility (e.g. DBNewerVersionThanService).

Examples

EXAMPLE 1

Gets an SQL update script to update the current schema to version 7.40.0.0. The resulting update_740.sql script is suitable for direct use with the SQL Server SQLCMD utility.

$update = Get-EnvTestDBVersionChangeScript -DatabaseName MyDb -TargetVersion 7.40.0.0
$update.Script > update_740.sql
<!--NeedCopy-->

Parameters

-DatabaseName

The name of the database containing the Citrix EnvTest Service schema to be updated.

Type: String
Position: Named
Default value: None
Required: True
Accept pipeline input: False
Accept wildcard characters: False

-TargetVersion

The required target service schema version of the update. This is the service schema version obtained after the update script is applied.

Type: Version
Position: Named
Default value: None
Required: True
Accept pipeline input: False
Accept wildcard characters: False

-AzureDatabase

Indicates that script is to update an Azure database. If this switch is not used when an Azure database is to be updated, the update will fail when an attempt is made to apply it.

Type: SwitchParameter
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

CitrixCommonParameters

This cmdlet supports the common Citrix parameters: -AdminAddress, -AdminClientIP, -BearerToken, -TraceParent, -TraceState and -VirtualSiteId. For more information, see about_CitrixCommonParameters.

CommonParameters

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

Inputs

None

You cannot pipe input into this cmdlet.

Outputs

PSObject

The Get-EnvTestDBVersionChangeScript cmdlet returns a PSObject containing a script that can be used to update the Citrix EnvTest Service database schema. The object has the following properties:

  • Script

    The raw text of the SQL script to apply the update.

  • CanUndo

    If true, indicates that after the update has been applied, a script to revert from the updated schema to the schema state prior to the update can be obtained. Because Get-<#= CmdletPrefix #>DBVersionChangeScript gets only update scripts relating to the current schema version, a script to revert an update can be obtained only after the update has been applied.

  • NeedExclusiveAccess

    If true, indicates that the update requires exclusive access to the Citrix <#= ServiceName #> Service’s schema while the update is applied; all Citrix <#= ServiceName #> Services must be shutdown during the update.

Notes

The PSObject returned by this cmdlet contains the following properties:

  • Script

    The raw text of the SQL script to apply the update, or null in the case when no upgrade path to the specified target version exists.

  • NeedExclusiveAccess

    Indicates whether all services in the service group must be shut down during the update or not.

  • CanUndo

    Indicates whether the generated script allows the updated schema to be reverted to the state prior to the update.

Scripts to update the schema version are stored in the database so any service in the service group can obtain these scripts. Extreme caution should be exercised when using update scripts. Citrix recommends backing up the database before attempting to upgrade the schema. Database update scripts may require exclusive use of the schema and so may not be able to execute while any EnvTest services are running. However, this depends on the specific update being carried out.

After a schema update has been carried out, services that require the previous version of the schema may cease to operate. The ServiceState parameter reported by the Get-EnvTestServiceStatus command provides information about service compatibility. For example, if the schema has been upgraded to a more recent version that a service cannot use, the service reports “DBNewerVersionThanService”.

If the command fails, the following errors can be returned:

  • NoOp

    The operation was successful but had no effect.

  • NoDBConnections

    The database connection string for the <#= ServiceName #> Service has not been specified.

  • DatabaseError

    An error occurred in the service while attempting a database operation.

  • DatabaseNotConfigured

    The operation could not be completed because the database for the service is not configured.

  • DataStoreException

    An error occurred in the service while attempting a database operation - communication with the database failed for various reasons.

  • PermissionDenied

    You do not have permission to execute this command.

  • AuthorizationError

    There was a problem communicating with the Citrix Delegated Administration Service.

  • CommunicationError

    There was a problem communicating with the remote service.

  • ExceptionThrown

    An unexpected error occurred. For more details, see the Windows event logs on the controller or the XenDesktop logs.

Get-EnvTestDBVersionChangeScript
August 9, 2024
Contributed by: 
C C
August 9, 2024
Contributed by: 
C C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.