The Application Deployment tool is based on MSBuild Tasks, which allow you to easily extend and/or customize your deployments. Using those tasks, you can automate deployment.
This document lists those tasks and describes how to use them in order to either extend what GeneXus does or automate your deployments.
The CreateDeployProject task will analyze what GeneXus objects must be included in the deployment based on the call tree of every selected object (or every main object if there is none). The output of this task is an MSBuild script with the extension .gxdproj containing every environment property and object (with its properties) needed for a successful deployment.
GeneXus provides a script called Deploy.msbuild (located at the root of the GeneXus installation) which is used by GeneXus itself and is a great starting point for automating your calls. Use the following command to create a deployment project of every main object in your Knowledge Base.
msbuild.exe <GX Installation directory>\deploy.msbuild /p:KBPath=<Path to your Knowledge Base>
This will create the deploy project (.gxdproj) file for the trunk version of the mentioned Knowledge Base for every main object in that version. There are a few properties you can add to change this behavior.
KBVersion: The name of the version to set as active.
KBEnvironment: The name of the environment in that version.
ProjectName: It will be the name of the generated .gxdproj file. If you leave this parameter empty, the DeploymentUnit parameter is taken to give a name to the .gxdproj file (concatenated with a timestamp value). If both ProjectName and DeploymentUnit are empty, the name of the .gxdproj file will be "MSBuildDeployment" concatenated with a timestamp.
ObjectNames: The names (with their types) of the objects to deploy (deployment units can also be selected) (ref.: How to specify an object list in a MSBuild task). If you leave this parameter empty, all the main objects of the KB are included in the deployment.
GX_PROGRAM_DIR: The path to your GeneXus installation.
APPLICATION_KEY: The new encryption key to set for your deployed application.
GXDeployFileProject: The path to the .gxdproj file generated, including the name of the file.
ApplicationServer: The default value (if the value is not passed) is Generic Servlet 6.0. It is recommended to always pass the Application Server that is the destination where the application will be deployed.
The Application server determines:
- Aspects of the web.xml (if it is going to be for JakartaEE or JavaEE)
- Descriptor aspects in the case of using native Soap. The gx_handler_chain.xml file is different for JakartaEE and JavaEE.
Other aspects such as package dependencies are not determined by the ApplicationServer since gradle is used to obtain the dependencies (because it is based on the Java Platform Support of the model).
TARGET_JRE: (Java only) version of the Java runtime where the deployed app will run. (Default is 9)
PACKAGE_FORMAT: (Java only) whether the engine must create a WAR or an EAR. (Default is 'Automatic'; the engine decides based on the selected objects)
SelectedObjectsOnly: When set to True, the deploy engine will not calculate the call tree of selected objects. Only the selected ones will be deployed.
TargetId: Default will be "Local", but you can set any of the supported Deploy Application Targets.
SourcePath: Defaults to the KB directory\model. The .gxdproj file is saved under <SourcePath>\web if Outputpath is not defined.
Outputpath: Where the .gxdproj file is saved.
You can also use the CallTreeLogFile property to get a log of the objects call tree.
MSbuild.exe /nologo /verbosity:minimal /ToolsVersion:14.0 "c:\GeneXus\deploy.msbuild"
/p:KBPath="c:\fullgx\kbaux"
/p:KBEnvironment=NetEnvironment
/p:KBVersion=kbaux
/p:ProjectName=DeployNet16
/p:ObjectNames="TestDeployUnit1"
/p:GX_PROGRAM_DIR="c:\fullgx\gxsaltostable"
/p:TimeStamp=DeployNet16
/p:Application_Key=863B7BE7A26B4276942E2C50FA1E0EAC
/p:ApplicationServer="IIS8" /p:TargetId="Local"
/p:SourcePath="c:\fullgx\kbaux\CSharpModel"
/p:AppName="DeployNet16"
/p:SelectedObjectsOnly="false"
/l:FileLogger,Microsoft.Build.Engine;logfile=c:\fullgx\temp\CreateDeploy.log
/p:CallTreeLogFile=c:\temp\CallTree.log
/t:CreateDeploy
The generated .gxdproj file is another MSBuild script that contains the necessary info to create the packaged application.
To generate the package (it can be a zip file in the case of .NET Framework and .NET or a war/jar/ear in the case of Java), you need to execute the generated script as follows:
msbuild.exe <Full path>\MSBuildDeployment_20190123103151.gxdproj
In this case, you can also set properties to tell the engine where the generated package will be deployed.
DeployFullPath: Full path to which a copy of packaged files will be copied to. You can use this path to compare different deployments.
Take a look at the generated .gxdproj file to see the defaults for DeployFullPath and DeployFileFullPath properties.
<!-- Destination paths -->
<PropertyGroup>
<DeployFileFullPath>$(SourcePath)\Deploy\$(DeployTarget)</DeployFileFullPath>
<DeployFullPath>$(DeployFileFullPath)\$(DeploymentUnit)\$(TimeStamp)</DeployFullPath>
</PropertyGroup>
To generate a YAML file documenting all deployed REST services and API objects, you must run something like the following:
MSBuild.exe /nologo /verbosity:detailed /ToolsVersion:14.0 "c:\GeneXus\DeploymentTargets\Docker\deploy.msbuild"
/p:GENERATE_OPEN_API_INTERFACE="True"
/p:GX_PROGRAM_DIR="c:\fullgx\gxsaltotrunk"
/p:GXDeployFileProject="c:\fullgx\kb\JavaModel\web\kbJavaEnvironmentDeploy1.gxdproj"
/t:Deploy
In this case, the GENERATE_OPEN_API_INTERFACE property is configured to activate the automatic generation of the YAML file according to the OpenAPI specification, documenting all the deployed REST services.
When GENERATE_OPEN_API_INTERFACE takes the value True, all objects within the Deployment Unit are expected to have the same configuration enabled. That is, the Generate OpenAPI interface property enabled at the object level.
The property GXDeployFileProject indicates the location of the .gxdproj file generated at the createdeploy MSBuild task.
GeneXus can also help you deploy to any of the supported cloud providers (deployment targets).
Every supported target is listed under the DeploymentTargets folder under the GeneXus installation. All of these targets have a deploy.msbuild file with a default task called Deploy.
MSBuild.exe /nologo /verbosity:minimal /ToolsVersion:4.0 "c:\GeneXus\DeploymentTargets\Docker\deploy.msbuild"
/p:DOCKER_BASE_IMAGE="tomcat:9-jdk11"
/p:DOCKER_MAINTAINER="seba <seba@example.com>"
/p:DOCKER_WEBAPPLOCATION="/usr/local/tomcat/webapps/"
/p:DOCKER_IMAGE_NAME="k8sdeployjavaenvironment"
/p:DOCKER_ENVVARS=""
/p:GENERATOR="Java"
/p:APPLICATION_NAME="DeploymentUnit2_20200130131103"
/p:DEPLOY_PATH="C:\GXmodels\junk\K8SDeploy\JavaModel\Deploy\DOCKER\DeploymentUnit2\20200130131103"
/t:Deploy
In sum, when the target is not local, the execution is in the following order.
Now, take AWSECS as an example.
1. The CreateDeploy task of the script deploy.msbuild of the GeneXus root is executed by MSBuild, to which the Target Id and the deploy targets must be passed as properties. For example:
MSbuild.exe /nologo /verbosity:minimal /ToolsVersion:14.0 "c:\GeneXus\deploy.msbuild"
/p:KBPath="c:\fullgx\kbaux"
/p:KBEnvironment=NetEnvironment
/p:KBVersion=kbaux
/p:ProjectName=DeployNet16
/p:TargetId="AWSECS"
/p:DEPLOY_TARGETS="C:\Genexus\DeploymentTargets\AWSECS\aws.targets"
/p:SourcePath="c:\fullgx\kbaux\CSharpModel"
/p:AppName="DeployNet16" /t:CreateDeploy
As a result, the .gxdproj file is obtained, where you will see the DeployTarget (TargetId information) and DeployTargetTask (DEPLOY_TARGETS information) properties.
2. The task CreatePackage of the gxdproj generated script is executed via MSBuild. As a result, you get a package on the local machine.
3. The Deploy task of deploy.msbuild (located under <GX>\DeploymentTargets\AWSECS) is executed to deploy to the PaaS.
When you deploy using the Application deployment tool inside the GeneXus IDE, generate the GeneXus Log to see in it the MSBuild tasks that are executed.
MSBuild Tasks
Team Development MSBuild Tasks
Application Deployment tool
How to specify an object list in a MSBuild task