IDeployPackage Interface

The Unisys.AgileBusiness.RuntimeAPI namespace contains the IDeployPackage interface that allows you to deploy an AB Suite generated package to a local or remote server and to create a clone of a builder generated package (.msi or .cab). Refer to Prerequisite for DPM for more information about the prerequisite information before cloning a builder generated package. The RuntimeFactory class includes methods to return the IDeployPackage objects.

Refer to Definition of IDeployPackage Interface for more information about the interface.

Namespace: Unisys.AgileBusiness.RuntimeAPI

Assembly: Unisys.AgileBusiness.RuntimeAPI (in Unisys.AgileBusiness.RuntimeAPI.dll)

Syntax

You can create the IPackageDeploy object by using the RuntimeFactory.GetDeployer()method.

IDeployPackage DeployPackage = 
Unisys.AgileBusiness.RuntimeAPI.RuntimeFactory.GetDeployer();

The IDeployPackage interface exposes the following methods.

Methods

Method	Description
PackageInstall()	Installs a generated package
ClonePackage()	Creates a deployment package for a new instance
CreatePartialPackage()	Creates partial MSIs and CAB files for an existing instance
UpdatePackage()	Updates the deployment package of an existing instance

Note: You must have local administrator privileges to use all the methods.

IDeployPackage.PackageInstall Method

This method allows you to install the generated package.

Syntax

PackageInstall(Unisys.AgileBusiness.RuntimeAPI.PackageInstallParameter parameter, 
Unisys.AgileBusiness.RuntimeAPI.PackageDeployCallBack callBack)

Arguments

parameter: PackageInstallParameter object

A data object class containing parameter information to install a package.

The PackageInstallParameter class exposes the following members.

Members

Name	Type	Description
DeployPackagePath	string	Absolute file path of the MSI or CAB files to be deployed
UserName	string	Application User Name, which must be in the format: "Domain\Username"
Password	SecureString	Application User password
DeploymentName	string	Folder on the target machine in which the MSI or CAB package is saved. The default value is the current package name.
RetainExistingDatabase	bool	Determine whether an existing database should be retained or a new database be recreated during the deploy process. The default value is true, which retains an existing database.
BackupExistingDatabase	bool	Back up an existing database. The default value is false.
TargetServerName	string	Target Runtime server name. If empty, the default value is localhost.
TargetDBRegistration	string	Target DB server registration name
TargetPath	string	Target application folder
TargetSystemName	string	Target System Name
TargetWinformPath	string	Target Winform folder
TargetDBName	string	Target DB name

callBack: RuntimeCallBack object

To allow a client program to handle the progress messages received from the PackageInstall(), ClonePackage(), CreatePartialPackage(), and UpdatePackage() methods, the client must

Implement the RuntimeCallBack class to receive the progress messages.
Pass the RuntimeCallBack object to the server in the PackageInstall() call.

The RuntimeCallBack class is an abstract class that implements the ICallBack interface. To obtain the deploy progress messages, the client must create a new class that inherits the RuntimeCallBack class. If the client passes this argument as null then no progress messages appear.

The RuntimeCallBack class exposes the following methods.

Methods

Method	Description	Parameter
CompletionStatus()	Completion status	int status
ProgressMessage()	Receives the progress message and message code	String message, Unisys.AgileBusiness.RuntimeAPI. MSGTYPE MSGTYPE
ReceiveAccept()	Receives the IAccept object from report.	Unisys.AgileBusiness.RuntimeAPI. IAccept pIAccept String prompt

Method

Description

Parameter

CompletionStatus()

Completion status

int status

ProgressMessage()

Receives the progress message and message code

String message, Unisys.AgileBusiness.RuntimeAPI. MSGTYPE MSGTYPE

ReceiveAccept()

Receives the IAccept object from report.

Unisys.AgileBusiness.RuntimeAPI. IAccept pIAccept

String prompt

Refer to Example of a RuntimeCallBack Class for more information about the syntax of these methods.

Note: A client program can also use the default class, ConsoleCallBackHandler, to get the progress messages in the PackageInstall method. If the client program desires to modify the progress message, the client can customize it by creating a class that implements the override methods of the RuntimeCallback class.

Definition of the ConsoleCallBackHandler Class

The ConsoleCallBackHandler class enables a client program to handle progress messages with the default template.

The ConsoleCallBackHandler class exposes the following methods.

Method	Description	Parameter
CompletionStatus()	Completion status	int status
ProgressMessage()	Receives the progress message and message code	String message, Unisys.AgileBusiness.RuntimeAPI. MSGTYPE MSGTYPE
ReceiveAccept()	Receives the IAccept object from report.	Unisys.AgileBusiness.RuntimeAPI. IAccept pIAccept String prompt

Method

Description

Parameter

CompletionStatus()

Completion status

int status

ProgressMessage()

Receives the progress message and message code

String message, Unisys.AgileBusiness.RuntimeAPI. MSGTYPE MSGTYPE

ReceiveAccept()

Receives the IAccept object from report.

Unisys.AgileBusiness.RuntimeAPI. IAccept pIAccept

String prompt

Example of a RuntimeCallBack Class

Following is a C# example of the class. This example is for a simple console client that indicates how you can write a callback message to the console output. The received messages are written to the console.

public class CallBackHandler : RuntimeCallBack
{
		protected override void ProgressMessage(string theMsg, MSGTYPE MSGTYPE)
		{
			Console.WriteLine(theMsg);
		}

		protected override void CompletionStatus(int Status)
		{
			Console.WriteLine("Operation Completed successfully", Status);
		}
		protected override void ReceiveAccept(IAccept pIAccept, string prompt)
		{
			Console.WriteLine(prompt);
			string lReply = Console.ReadLine();
			pIAccept.Reply(lReply);
		}
}

Example of a ConsoleCallBackHandler Class

Following is a C# example of this class with default template.

ConsoleCallBackHandler callBack = new ConsoleCallBackHandler();
StatusInfo status = deploy.PackageInstall(param, callBack);

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

SecurityHelper Class

This public class sets the default security required for installing a generated package. The class exposes the following members.

Members

Name	Type	Description
CoInitializeSecurity	int	Enables setting different security parameters apart from the default security.
SetSecurity	int	Set the default security required for deploying.

Using the IDeployPackage Interface for the PackageInstall() method

To use the interface through the C# example, perform the following:

Create a new C# Class Library in Microsoft Visual Studio.
Add a reference to the following assembly that you need when calling from the Class Library:
- Unisys.AgileBusiness.RuntimeAPI.dll (from <AB Suite 7.0 Installation directory>\bin64 folder)

Add the following code to perform an AB Suite system deployment to a local server.

Note: If a client wants to receive the progress messages, the second argument of the PackageInstall method must never be null.

		namespace SampleDeployer
		{
			using System;
			using Unisys.AgileBusiness.RuntimeAPI;
			using System.Security;
			class Program
			{
				static void Main(string[] args)
				{
					//Get the deployer
					IDeployPackage deployer = RuntimeFactory.GetDeployer();
					//GetDeployer sets the security
					SecureString securePwd = new SecureString();
					string pass = @"Password";
					foreach (char c in pass) securePwd.AppendChar(c);
					//Construct the PackageInstallParameter
					PackageInstallParameter param = new PackageInstallParameter()
					{
						DeployPackagePath=
						@"C:\TEMP\stagingarea\NGENSampleDeploy.msi",
						UserName = @"Appuser",
						Password = securePwd
					};
					//Get the callback object for progress message.
					CallBackHandler callBack = new CallBackHandler();
					StatusInfo statusInfo = deployer.PackageInstall(param, callBack);
			}
		}

Build the Class Library.

IDeployPackage.ClonePackage Method

This method allows you to create a deployment package for the new instance.

Syntax

ClonePackage(Unisys.AgileBusiness.RuntimeAPI.ClonePackageParameter parameter,
Unisys.AgileBusiness.RuntimeAPI.RuntimeCallBack callBack)

Arguments

parameter: ClonePackageParameter object

The object consists of all Clone package user input.

The ClonePackageParameter class exposes the following list of members.

Members

Name	Type	Description
BuilderGeneratedPackage	string	Absolute path, relative file path, or network path to the builder generated package; .msi or .cab. This member is mandatory. For example: BuilderGeneratedPackage = @"C:\TEMP\stagingarea\Sample.msi" BuilderGeneratedPackage = @“C:\AB Suite 7.0\Data\public\ PrototypePackageMessagesSimple.msi" BuilderGeneratedPackage = @"..\Sample.msi" BuilderGeneratedPackage = @"\\network\my folder\ BuilderGeneratedPackage.msi"
OverWrite	bool	Overwrites OutputPath package. The default value is false. For example: `OverWrite = true`
TargetPackagePath	string	Output package path The default path is "MyDocuments". For example: `TargetPackagePath = @"C:\ClonedPackages"`
DBName	string	Database name The default value is the existing Instance name appended with "DB ". For example: For Sample instance, type `DBName = @"SAMPLEDB"`
DBRegistration	string	Database server registration name The default value is the builder generated value. For example: `DBRegistration = @"SQLSERVER"`
DBSchemaName	string	Database schema name The default value is the existing Instance name. For example: `DBSchemaName = @"SAMPLESCHEMA"`
SystemName	string	System name or new package name The default value is the builder generated value appended with "Clone". For example: `SystemName = @"SAMPLECLONE"`
PackageName	string	Package name of the new .msi or .cab package name The package name gets modified if the instance name is updated until the package name is set manually. The default value is the builder generated value appended with "Clone".
PackageInstallationDirectory	string	Absolute path to the builder generated instance package The default value is the builder generated value appended with "Clone". For example: `PackageInstallationDirectory = @"C:\ABSuite\Systems\SampleClone"`

callBack: RuntimeCallBack object
Refer to callback argument of the PackageInstall() method for more information.

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

Using the IDeployPackage Interface for the ClonePackage() method

To use the interface for creating a deployment package of a new instance through the C# example, perform the following:

Create a new C# Class Library in Microsoft Visual Studio.
Add a reference to the following assembly that you need when calling from the Class Library:
- Unisys.AgileBusiness.RuntimeAPI.dll (from <AB Suite 7.0 Installation directory>\bin64 folder)

Add the following code to create a deployment package.

Note: If a client wants to receive the progress messages, the second argument of the ClonePackage method must never be null.

		namespace SampleDPM
		{
			using System;
			using Unisys.AgileBusiness.RuntimeAPI;
			class Program
			{
				static void Main(string[] args)
				{
					//Get the deployer
					IDeployPackage deployer = RuntimeFactory.GetDeployer();
					//Construct the ClonePackageParameter
					ClonePackageParameter param = new ClonePackageParameter()
					{
						BuilderGeneratedPackage =
						@"C:\TEMP\stagingarea\Sample.msi",
						TargetPackagePath = @"C:\ClonedPackages",
						DBName = @"SAMPLEDB",
						DBSchemaName = @"SAMPLESCHEMA",
						DBRegistration = @"SQLSERVER",
						SystemName = @"SAMPLECLONE",
						PackageName = @"SAMPLECLONE",
						PackageInstallationDirectory = 
						@"C:\ABSuite\Systems\SampleClone",
						OverWrite = true
					};
					//Get the callback object for progress message
					CallBackHandler callBack = new CallBackHandler();
					//Execute ClonePackage
					StatusInfo statusInfo = deployer.ClonePackage(param, callBack);
				}
			}
		}

Build the Class Library.

IDeployPackage.CreatePartialPackage Method

This method allows you to create a partial MSI package for an existing instance. A partial package is used to clone Report MSIs.

Syntax

CreatePartialPackage(Unisys.AgileBusiness.RuntimeAPI.PartialPackageParameter
parameter, Unisys.AgileBusiness.RuntimeAPI.RuntimeCallBack callBack)

Arguments

parameter: PartialPackageParameter object

The object consists of partial package input.

The PartialPackageParameter class exposes the following list of members.

Members

Name	Type	Description
BuilderGeneratedPackage	string	Absolute path, relative file path, or network path to the builder generated package; .msi or .cab. This member is mandatory. For example: BuilderGeneratedPackage = @"C:\TEMP\stagingarea\SampleReports.msi"
OverWrite	bool	Overwrites OutputPath package. The default value is false. For example: `OverWrite = true`
TargetPackagePath	string	Output package path The default path is "MyDocuments" For example: `TargetPackagePath = @"C:\ClonedPackages"`
DpmGeneratedPackage	string	Absolute path, relative file path, or network path to the DPM generated instance package This member is mandatory. For example: `DpmGeneratedPackage = @"C:\ClonedPackages\SampleClone.msi"`
PackageName	string	Package name of the new .msi or .cab package name The default value is the builder generated value appended with "Clone".
ReportName	string	New name for a report in a single-report package (.cab).

callBack: RuntimeCallBack object
Refer to callback argument of the PackageInstall() method for more information.

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

Using the IDeployPackage Interface for the CreatePartialPackage() method

To use the interface for creating a partial MSI package of the existing instance, perform the following:

Create a new C# Class Library in Microsoft Visual Studio.
Add a reference to the following assembly that you need when calling from the Class Library:
- Unisys.AgileBusiness.RuntimeAPI.dll (from <AB Suite 7.0 Installation directory>\bin64 folder)

Add the following code to create a partial MSI package.

Note: If a client wants to receive the progress messages, the second argument of the CreatePartialPackage method must never be null.

		namespace SampleDPM
		{
			using System;
			using Unisys.AgileBusiness.RuntimeAPI;
			class Program
			{
				static void Main(string[] args)
				{
					//Get the deployer
					IDeployPackage deployer = RuntimeFactory.GetDeployer();
					//Construct the PartialPackageParameter
					PartialPackageParameter param = new PartialPackageParameter()
					{
						BuilderGeneratedPackage = 
						@"C:\TEMP\stagingarea\SampleReports.msi",
						DpmGeneratedPackage = @"C:\ClonedPackages\SampleClone.msi",
						TargetPackagePath = @"C:\ClonedPackages",
						PackageName = @"SAMPLECloneReports",
						OverWrite = true
					};
					//Get the callback object for progress message
					CallBackHandler callBack = new CallBackHandler();
					//Execute CreatePartialPackage
					StatusInfo statusInfo = deployer.CreatePartialPackage(param, callBack);
				}
			}
		}

Build the Class Library.

IDeployPackage.UpdatePackage Method

This method allows you to update the deployment package of the existing instance.

Syntax

UpdatePackage(Unisys.AgileBusiness.RuntimeAPI.UpdatePackageParameter parameter,
Unisys.AgileBusiness.RuntimeAPI.RuntimeCallBack callBack)

Arguments

parameter: UpdatePackageParameter object

The object consists of Updatepackage user input.

The UpdatePackageParameter class exposes the following list of members.

Members

Name	Type	Description
BuilderGeneratedPackage	string	Absolute path, relative file path, or network path to the builder generated package; .msi or .cab. This member is mandatory. For example: BuilderGeneratedPackage = @"C:\TEMP\stagingarea\Sample.msi"
OverWrite	bool	Overwrites OutputPath package. The default value is false. For example: `OverWrite = true`
TargetPackagePath	string	Output package path The default path is "MyDocuments" For example: `TargetPackagePath = @"C:\ClonedPackages"`
DBName	string	Database name For example: `DBName = @"CLONESAMPLEDB"`
DBRegistration	string	Database server registration name For example: `DBRegistration = @"SQLSERVER"`
PackageName	string	Package name of the new .msi or .cab package name. The default value is the builder generated value appended with "Clone".
DBSchemaName	string	Database schema name For example: `DBSchemaName = @"CLONEDSAMPLESCHEMA"`
DpmGeneratedPackage	string	Absolute path, relative file path, or network path to the DPM generated instance package This member is mandatory. For example: `DpmGeneratedPackage = @"C:\ClonedPackages\SampleClone.msi"`
PackageInstallationDirectory	string	Absolute path to builder generated instance package For example: `PackageInstallationDirectory = @"C:\ABSuite\Systems\SampleClone"`

callBack: RuntimeCallBack object
Refer to callback argument of the PackageInstall() method for more information.

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

Using the IDeployPackage Interface for the UpdatePackage () method

To use the interface for updating the deployment package through the C# example, perform the following:

Create a new C# Class Library in Microsoft Visual Studio.
Add a reference to the following assembly that you need when calling from the Class Library:
- Unisys.AgileBusiness.RuntimeAPI.dll (from <AB Suite 7.0 Installation directory>\bin64 folder)

Add the following code to update the deployment package.

Note: If a client wants to receive the progress messages, the second argument of the UpdatePackage method must never be null.

		namespace SampleDPM
		{
			using System;
			using Unisys.AgileBusiness.RuntimeAPI;
			class Program
			{
				static void Main(string[] args)
				{
					//Get the deployer
					IDeployPackage deployer = RuntimeFactory.GetDeployer();
					//Construct the UpdatePackageParameter
					UpdatePackageParameter param = new UpdatePackageParameter()
					{
						BuilderGeneratedPackage = 
						@"C:\TEMP\stagingarea\Sample.msi",
						DpmGeneratedPackage = @"C:\ClonedPackages\SampleClone.msi",
						TargetPackagePath = @"C:\ClonedPackages",
						DBName = @"CLONESAMPLEDB",
						DBSchemaName = @"CLONEDSAMPLESCHEMA",
						DBRegistration = @"SQLSERVER",
						PackageName = @"SAMPLEPACKAGE",
						PackageInstallationDirectory = 
						@"C:\ABSuite\Systems\SampleClone",
						OverWrite = true
					};
					//Get the callback object for progress message
					CallBackHandler callBack = new CallBackHandler();
					//Execute UpdatePackage
					StatusInfo statusInfo = deployer.UpdatePackage(param, callBack);
				}
			}
		}

Build the Class Library.

Definition of the IDeployPackage Interface

Following is the definition of the IDeployPackage interface.

		namespace Unisys.AgileBusiness.RuntimeAPI
		{
			public interface IDeployPackage
			{
				StatusInfo ClonePackage(ClonePackageParameter parameter, 
				RuntimeCallBack callBack);
				StatusInfo CreatePartialPackage(PartialPackageParameter parameter,
				RuntimeCallBack callBack);
				StatusInfo PackageInstall(PackageInstallParameter parameter, 
				RuntimeCallBack callBack);
				StatusInfo UpdatePackage(UpdatePackageParameter parameter, 
				RuntimeCallBack callBack);
			}
		}