GeneXus MSBuild Tasks let you automate all about Knowledge Base building (i.e. automating import, specification, generation and compilation tasks among others). In a fully declarative way (creating and programming scripts in XML format) you can easily specify the tasks to be done later with no user interaction.
This technology helps you create night builds of the applications you are developing, running automatic tests on them, etc.

GeneXus MSBuild Tasks are based on Microsoft Build Engine (MSBuild). It is the new build platform for Microsoft and Visual Studio. It is a generic, extensible build platform and is part of Framework 2.0 (meaning it is free).

The basic script

The following is a simple script intended for opening an existing Knowledge Base and building all its objects.

<Project DefaultTargets="OpenAndBuildAll" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
   <Import Project="C:\Program Files\Artech\GeneXus\GeneXusX\Genexus.Tasks.targets" />
   <Target Name="OpenAndBuildAll">
     <OpenKnowledgeBase Directory="C:\MyKnowledgeBases\TestKnowledgeBase" />
     <BuildAll />
   </Target>
</Project>

The Import directive (second script line) tells MSBuild where to find extensions specific to GeneXus. This is a required directive. Lines 3 thru 6 identify a "Target" (something to be built) and specify what actions or "Tasks" must be accomplished to complete it. In this case, the tasks are OpenKnowledgeBase and BuildAll.

As you may have noticed, MSBuild coding is simple but powerful. You can take a closer look at all its features here.

Task list

The following task list describes all GeneXus MSBuild tasks (provided in GeneXus.MSBuild.Tasks.dll) and their parameters. It is divided into Basic and Advanced tasks. Basic tasks are those most commonly used. On the other hand, the advanced ones are only used in very specific situations. Please note that this classification is quite arbitrary.

Basic tasks

  • CreateKnowledgeBase

Creates a Knowledge Base in the specified directory based on a KB template.

Syntax

<CreateKnowledgeBase
   Directory="kbDirectory)"
   Template="kbTemplate)"
   Overwrite="true|false"
   IntegratedSecurity="true|false"
   UserId="userId"
   Password="password"
   CreateDbInKbFolder="true|false"
   ServerInstance="instance"
   DBName="dbName"
   Language="language"
/>

Options

Directory is the directory (absolute or relative) where the Knowledge Base should be created. REQUIRED

Template is the name of a Knowledge Base template. They are exported with GeneXus, and there are two of them:

  • CSharp.KBTemplate

Sets properties for a CSharp Generator

  • Java.KBTemplate

Sets properties for a Java Generator

Until now these files are provided by Artech and should not be changed. Future releases will allow you to create your templates. REQUIRED

Overwrite is true or false (default value) to delete the folder before creating the KB

IntegratedSecurity: "true" to use trusted connection; "false" to use specific user Id and password. Default: true.

UserId: user name to use when IntegratedSecurity is set to false. 

Password: password to use when IntegratedSecurity is set to false. 

CreateDbInKbFolder: "true" to create KB database files in the Knowledge Base folder; "false" to use the DBMS' default data folder. Default: true.

ServerInstance: server name and the instance of the SQLServer, for example: ".\SQLEXPRESS" or "localhost". If you don't use this property, the local default instance will be used.

DBName: name of the KB database. The default is the KB name prefixed with "GX_KB_".

Language: the language of the Knowledge Base to create.

Samples

Create a CSharp Knowledge Base in directory C:\MyKnowledgeBases.

<CreateKnowledgeBase Directory="C:\MyKnowledgeBases" Template="CSharp.KBTemplate" />
  • Import

Imports an import file into the currently opened Knowledge Base.

Syntax

<Import File="$(ImportFileName)" AutomaticBackup="$(AutomaticBackup)" ImportType="$(ImportType)" LanguageTranslations="$(LanguageTranslations)" RedefineExternalPrograms="$(RedefineExternalPrograms)" ImportKBInformation="$(ImportKBInformation)" />

Options

File: is the fully or partially qualified name of an Import File (.XPZ). REQUIRED

AutomaticBackup: defines whether an automatic backup is generated.

ImportType: Available options are: AllObjects, DifferentObject and NewerObjects.

LanguageTranslations: Available options are: Update, Keep, ReplaceAll.

RedefineExternalPrograms: check the Redefine External Programs Property property.

ImportKBInformation: defined wether KB/Version/Environment properties are imported. Possible values are "false" default and "true".  This is implemented as from GeneXus X  Evolution 3 Upgrade 2.

Samples

Import file c:\MyExports\ImportTestFile.xpz into the currently opened Knowledge Base.

<Import File="c:\MyExports\ImportTestFile.xpz" />

Note: If MSbuild.exe is executed with /verbosity:detailed each object imported will be shown:

Importing Attribute 'ClientAddress'...
Importing Attribute 'ClientBalance'...
Importing Transaction 'Client'...
Importing Procedure 'IsAuthorized'...
  • OpenKnowledgeBase

Opens the Knowledge Base in the specified directory.

Syntax

<OpenKnowledgeBase Directory="$(KBDirectory)" TargetModelId="$(ModelId)" />

Options

Directory: $(KBDirectory) is the directory (absolute or relative) where the Knowledge Base is located. REQUIRED (unless you use MDFPath; see below)

MDFPath: Instead of using Directory, you can use this to choose an mdf to open (instead of the .gxw file). 

TargetModelId: $(ModelId) is the ID of the Target model when working in a Version different than the Trunk Version. This parameter is optional, it is recommended to use the tasks SetActiveVersion and SetActiveEnvironment to position on the required version and environment.

Samples

Open a Knowledge Base in directory C:\MyKnowledgeBases.

<OpenKnowledgeBase Directory="C:\MyKnowledgeBases" />
  • SetEnvironmentProperty

Sets the value of a given environment property.

Syntax

<SetEnvironmentProperty Name="$(PropertyName)" Value="$(PropertyValue)"/>

Options

Name: $(PropertyName) is a valid property name. REQUIRED.

Value: $(PropertyValue) is valid value for the specified property. REQUIRED

Note: Available since: GeneXus X Evolution 1 Upgrade 2.

  • SetVersionProperty

Sets the value of a given version property.

Syntax

<SetVersionProperty Name="$(PropertyName)" Value="$(PropertyValue)"/>

Options

Name: $(PropertyName) is a valid property name. REQUIRED.

Value: $(PropertyValue) is valid value for the specified property. REQUIRED

Note: Available since: GeneXus X Evolution 1 Upgrade 2.

  • SetKnowledgeBaseProperty

Sets the value of a Knowledge Base property.

Syntax

<SetKnowledgeBaseProperty Name="$(PropertyName)" Value="$(PropertyValue)" />

Options

Name: $(PropertyName) is a valid property name. REQUIRED. 

Value: $(PropertyValue) is valid value for the specified property. REQUIRED

Note: Available since: Genexus X Evolution 1 Build 23131.

  • SetDataStoreProperty

Sets the value of a given data store property.

Syntax

<SetDataStoreProperty Datastore="$(DataStoreName)" Name="$(PropertyName)" Value="$(PropertyValue)" />

Options

Datastore: $(DataStoreName) is the name of a Data Store defined in the Knowledge Base. Usually the value of this name is "Default".

  • Optional, default value "Default", not implemented yet.

Name: $(PropertyName) is a valid model property name. REQUIRED

Value: $(PropertyValue) is valid value for the specified property. REQUIRED

  • SetGeneratorProperty

Sets the value of a given generator property.

Syntax

<SetGeneratorProperty Generator="$(GeneratorName)" Name="$(PropertyName)" Value="$(PropertyValue)" />

Options

Generator: $(GeneratorName) is the name of a Generator defined in the Knowledge Base. Usually the value of this name is "Default" or "Reorg".

  • Optional, the default value is "Default", not implemented yet.

Name: $(PropertyName) is a valid model property name. REQUIRED

Value: $(PropertyValue) is valid value for the specified property. REQUIRED

  • Export

Exports the currently opened Knowledge Base to a file.

Syntax

<Export File="$(ExportFileName)" Objects="$(ObjectList)" DependencyType="$(depType)" ReferenceType="$(refType)" IncludeGXMessages="$(includeGXMsg)" IncludeUntranslatedMessages="$(includeUtMsg)" />

Options

File: $(ExportFileName) is the fully or partially qualified name of an export file (.XPZ). REQUIRED

Objects: $(ObjectList) is the list of objects to specify (see the section about object lists in MSBuild tasks.) Unless you use this parameter, all objects in the Knowledge Base will be exported.

DependencyType: when using the Objects parameter, you may set DependencyType to “ReferencedBy” or “ReferencesTo” to also export objects that either is referenced by or reference to, respectively, the original set. Default: “ReferencesTo”.

ReferenceType: controls what kinds of references are used when adding objects with a given DependencyType. Possible values are: “None” (no reference is considered, which in fact voids the effect of the DependencyType parameter); “Minimal” (only the references that would be needed when importing in a new KB); “Hard” (all hard references); and “All”. Default: “Minimal”.

IncludeGXMessages: when exporting languages, standard GeneXus messages are not exported unless you use this parameter. Possible values: “true” and “false”. Default “false”.

IncludeUntranslatedMessages: exporting languages, untranslated messages are not exported unless you use this parameter. Possible values “true” and “false”. Default “false”.

Samples

Export to file c:\MyExports\ImportTestFile.xpz the content of the currently opened Knowledge Base.

<Export File="c:\MyExports\ImportTestFile.xpz" />
  • ExportAll

           Same as Export, but you don't have to specify an object list, as it exports the entire  KB.

  • ExportKBInfo
  • BuildAll

Builds all objects in a Knowledge Base optionally forcing its generation. Building means performing all tasks required to successfully run the application. Knowledge Base objects are specified, generated and compiled. If a reorganization is required, it is also automatically run.

Syntax

<BuildAll ForceRebuild="true|false" CompileMains="true|false" DetailedNavigation="true|false" />

Options

ForceRebuild: indicates whether a rebuild should be performed; the default value is False. 

CompileMains: if false it will compile only the Developer menu, if true it will also compile all main objects in the KB.

DetailedNavigation: indicates whether a detailed navigation should be done; the default value is False.

Samples

Build, without forcing generation, all objects in the currently opened Knowledge Base.

<BuildAll ForceRebuild="false" />

Note: Available since Genexus X Evolution 1 Build 20699.

  • BuildOne

Builds the object specified and all objects it calls (direct or indirect). Building means performing all tasks required to successfully run the application. Objects (the one selected and those called by it) are specified, generated and compiled. If a reorganization is required, it is also automatically run.

Syntax

<BuildOne ForceRebuild="true|false" BuildCalled="true|false" ObjectName="$(ObjectName)" DetailedNavigation="true|false" />

Options

ForceRebuild: indicates whether a rebuild should be performed; the default value is False. 

ObjectName: is the name of a existing object having the Main property set to true. REQUIRED

DetailedNavigation: indicates whether a detailed navigation should be done; the deafult value is False.  

Samples

Build object MyMainMenu and all called objects in the currently opened Knowledge Base.

<BuildOne ObjectName="MyMainMenu" />

Note: Available since Genexus X Evolution 1 Build 20699.

  • DeleteObject

Removes the object specified from the Knowledge Base.

Syntax

<DeleteObject Name="$(ObjectName)" Type="$(ObjectType)" FailWhenNone="true|false"  />

Options

Name: $(ObjectName) is the name of the object to be deleted. REQUIRED

Type: $(ObjectType) is the object's type. Possible values are: Folder, Category, Attribute, DataProvider, Domain, SubtypeGroup, Language, SDT, Theme, Transaction, WebPanel, File, Image, Document or TransactionsDiagram. REQUIRED

FailWhenNone: error if the object doesn't exist.

  • Run

Builds the specified object and all objects it references (direct or indirectly), and executes it. The object must have the Main property set to True. Building means performing all tasks required to successfully run the object. Objects (the one selected and those called by it) are specified, generated and compiled. If a reorganization is required, it is also automatically run. This behavior can be changed specifying Build=false, where only the execution of the object is performed.

Syntax

<Run ForceRebuild="true|false" Build="true|false" BuildCalled="true|false" ObjectName="$(ObjectName)" DetailedNavigation="true|false" />

Options

ForceRebuild: indicates whether a rebuild should be performed; the default value is False. 

Build: indicates wheter object shout be build as well, the default value is True. This is implemented as from GeneXus X  Evolution 3 Upgrade 3

BuildCalled: indicates whether called objects should be build as well; the default value is True.

ObjectName: is the name of an existing object having the Main property set to True. REQUIRED

DetailedNavigation: indicates whether a detailed navigation should be done; the default value is False.  

Parameters: allows you to pass parameters to an object's run

Samples

Build object MyMainMenu and all called objects in the currently opened Knowledge Base, and execute object MyMainMenu.

<Run ObjectName="MyMainMenu" />

Note: Available since Genexus X Evolution 1 Build 20699.

Advanced tasks

These GeneXus MSBuild tasks should not be used frequently. They are intended for very specific situations.

  • CreateDatabase

Creates Database objects (tables, indices, constraints, etc.) as required for the currently opened Knowledge Base.

Syntax

<CreateDatabase />

Options

ExecuteCreate

  • Reorganize

Compiles and Executes the last Impact Data Base specified.

Syntax

<Reorganize />

  • SpecifyAll

Specifies all objects in a Knowledge Base optionally forcing its generation (but not generating).

Syntax

<SpecifyAll ForceRebuild="true|false" DetailedNavigation="true|false" />

Options

ForceRebuild: indicates whether a rebuild should be performed; the default value is False. 

DetailedNavigation: indicates whether a detailed navigation should be done; the default value is False.  

Samples

Specify, without forcing generation, all objects in the currently opened Knowledge Base.

<SpecifyAll ForceRebuild="false" />

Note: Available since Genexus X Evolution 1 Build 20699.

  • GenerateOnly

Generates all objects whose generation is pending either by the execution of a previous SpecifyOne or SpecifyAll tasks. It does not compile generated objects.

Syntax

<Generate />

  • Compile

Compiles the object specified in the optional parameter ObjectName. If the ObjectName parameter is omitted, the Developer Menu is compiled.

Syntax

<Compile ObjectName="$(ObjectName)" />

Option

ObjectName: is the name of an existing object having the Main property set to true.

  • Optional, default to compile the Developer Menu.

Samples

Compile object MyMainMenu in the currently opened Knowledge Base.

<Compile ObjectName="MyMainMenu" />
  • UpdateWorkingModel

Updates the working model with information of the corresponding design model. This task should be executed with care as once executed, GeneXus will "forget" all design changes made. If, for example, a Database change was required due to design changes and you execute the UpdateWorkingModel task, those changes will not be applied to your Database.

Syntax

<UpdateWorkingModel />

  • WriteKnowledgeBaseSchema

Writes a .xml file with the schema of the database that is defined by a GeneXus project.

Syntax

<WriteKnowledgeBaseSchema File="$(KnowledgeBaseSchemaFile)" DesignModel="true|false" SortByName="true|false" />

Option

File: $(KnowledgeBaseSchemaFile) is the fully or partially qualified name of a Knowledge Base Schema file to be created. REQUIRED

DesignModel: "true" to display design model information; "false" to display target model information. Default: false. This is implemented as from GeneXus X  Evolution 2 Upgrade 7.

SortByName: "true" to display table and index information ordered by name. Default: false. This is implemented as from GeneXus X  Evolution 2 Upgrade 7.

  • WriteDatabaseSchema

Writes a .xml file with the schema of the database that is configured in a GeneXus project.

Syntax

<WriteDatabaseSchema File="$(DataBaseSchemaFile)" />

Option

File: $(DataBaseSchemaFile) is the fully or partially qualified name of the Database Schema file to be created. REQUIRED

  • CompareSchemas

Compares files representing a Database schema and a Knowledge Base schema. You may have created these files using WriteDatabaseSchema and WriteKnowledgeBaseSchema tasks. This is useful to know if the database schema is synchronized with the schema defined by the KB.

Syntax

<CompareSchemas DBFile="$(DataBaseSchemaFile)" KBFile="$(KnowledgeBaseSchemaFile)" DiffFile="$(ComparisonDifferenceFile)" />

Options

DBFile: $(DataBaseSchemaFile) is the fully or partially qualified name of the Database Schema file to be compared. REQUIRED

KBFile: $(KnowledgeBaseSchemaFile) is the fully or partially qualified name of a Knowledge Base Schema file to be compared. REQUIRED

DiffFile: $(ComparisonDifferenceFile) is the fully or partially qualified name of a file generated with the differences in the schemas comparison.

  • CheckKnowledgeBase

The CheckKnowledgeBase task checks the consistency of a KnowledgeBase.

Syntax

<CheckKnowledgeBase Fix="true|false" />

Option

Fix: determines if errors are fixed or not.

Note: Available since Xev1 Upgrade #3.

  • GetCategoryObjects

The GetCategoryObjects task returns a list of all objects belonging to a given category.

Syntax

<GetCategoryObjects CategoryName="TestCategory">
   <Output TaskParameter="Objects" PropertyName="ObjList"/>
</GetCategoryObjects>

<Message Text="Objects in TestCategory = $(ObjList)"/> 

Available since Xev2.

  • SetConfiguration

            Changes configuration; it's the combo in the IDE that shows Release, Debug, Performance Test, Live Editing. 

            Syntax

<SetConfiguration Configuration="$(Configuration)"/>

Options

Configuration: $(Configuration) is a valid configuration: "Release", "Debug", or "Performance Test". Note that "Live Editing" is not yet included for this task.

  • SetCredential

            The SetCredential task changes the GeneXus Account that is later used for some services, for example for deploying to cloud; it's the same one that you can change in the IDE in Tools>GeneXus Account 

            Syntax

<SetCredential UserName="$(UserName)" UserPassword="$(UserPassword)" Persist="true|false" />

Options

UserName: $(UserName) is a valid GeneXus Account username. 

UserPassword: &(UserPassword) is the GeneXus Account password that corresponds to that username. 

Persist: determines if the information persists or if it's only for this session.

Teamworking

See also Team Development MSBuild Tasks

Versioning

  • CreateVersion

Creates a new frozen version from the active or specified version.

Syntax

<CreateVersion VersionName="$(VersionName)" VersionDescription="$(VersionDescription)" Parent="$(ParentName)" />

Options

VersionName: is the name that will be assigned to the Version. REQUIRED

VersionDescription: is an optional description for the Version. Parent is the name of an existing development version. The special value *Trunk or the Knowledge Base's name can be used to name the root element of the version tree.

Parent: is the name of an existing development or frozen version. The special value *Trunk or the Knowledge Base's name can be used to name the root element of the version tree.

  • SetActiveVersion

Sets a development version as "active" or current. All subsequent commands that do not specify a development version or frozen version work on this version.

Syntax

<SetActiveVersion VersionName="$(VersionName)" />

Options

VersionName: is the name of an existing version. REQUIRED

  • RevertToVersion

Reverts (overwrites) the Root version with the version specified as the parameter. Any changes to the Root version are lost.

Syntax

<RevertToVersion VersionName="$(VersionName)" />

Options

VersionName: is the name of an existing version. REQUIRED

  • MergeVersions

Makes a merge between two versions.

Syntax

<MergeVersions SourceVersion="$(SourceVersion)" TargetVersion="$(TargetVersion)" SinceDate="$(SinceDate)" />

Options

SourceVersion: is the Version from which the changes will be bring. REQUIRED

TargetVersion: is the Version where the changes will be applied. If not indicated, the active Version will be used.

SinceDate: is the beginning date to consider the changes to apply. If not indicated, all changes will be applied. The formats supported by the parameter are detailed here: http://msdn.microsoft.com/en-us/library/az4se3k1.aspx. Note that some formats depend on on the regional configuration of the machine. An independent format is suggested, i.e."yyyy-mm-dd hh:MM:ss".

This task is implemented as from GeneXus X  Evolution 3 Upgrade 2.

Environment handling

  • CreateEnvironment

Creates a new environment in the active or specified version.

Syntax

<CreateEnvironment EnvironmentName="$(EnvironmentName)" EnvironmentDescription="$(EnvironmentDescription)" Parent="$(ParentName)"] />

Options

Name: is the name that will be assigned to the Environment. REQUIRED

Template: is an optional description for the Environment. Parent is the name of an existing Version. The special value *Trunk or the Knowledge Base's name can be used to name the root element of the version tree.

  • SetActiveEnvironment

Sets an environment as the active or current one. All subsequent commands that do not specify an environment work on this environment. The Environment must exist in the active Version.

Syntax

<SetActiveEnvironment EnvironmentName="$(EnvironmentName)" />

Option

EnvironmentName: is the name of an existing Environment. REQUIRED

Output

When you run an MSBuild script, the results are displayed in the standard output by default. You can also indicate an XML output to be generated to a file, using the following parameter:

XmlOutputFile="$(XmlOutputFile)"

Executing MSBuild Scripts

MSBuild scripts can be executed from the command line by invoking MSBuild.exe (stored in folder C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727 if you have installed all products leaving default path names). A sample command line to execute the script called Demo.msbuild is as follows.

msbuild Demo.msbuild

Note

Be sure to execute the MSBuild tasks using the Microsoft.Net Framework 32 bits up to 3.5 version (4.0 not supported). If you instead use the 64 bits framework the following error will be shown:

error : Could not load file or assembly 'gxio, Version=0.0.0.0, Culture=neutral, PublicKeyToken=6f5bf81c27b6b8aa' or one of its dependencies. The system cannot find the file specified.

Sample scripts

Test all GeneXus MSBuild Tasks

This tests just invokes every GeneXus MSBuild Task

<Project DefaultTargets="Test" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Import Project="C:\Program Files\Artech\GeneXus\GeneXusX\GeneXus.Tasks.targets" />

    <PropertyGroup>
        <KBTemplate>csharp.kbtemplate</KBTemplate>
        <KBPath>c:\TestKnowledgeBases</KBPath>
    </PropertyGroup>

	<Target Name="CreateKnowledgeBase">
		<RemoveDir Directories="$(KBPath)" />
		<CreateKnowledgeBase Directory="$(KBPath)\TestCreate" Template="$(KBTemplate)" />
	</Target>
	<Target Name="Import">
		<Import File="c:\NameOfFileToImport.xpz" />
	</Target>
	<Target Name="OpenKnowledgeBase">
		<OpenKnowledgeBase Directory="$(KBPath)\TestCreate" />
	</Target>
	<Target Name="Export">
		<Export File="c:\NameOfDistributionFile.xpz" />
	</Target>
	<Target Name="Reorganize">
		<Reorganize />
	</Target>
	<Target Name="SpecifyAll">
		<SpecifyAll ForceRebuild="false" />
	</Target>
	<Target Name="Generate">
		<Generate />
	</Target>
	<Target Name="Compile">
		<Compile ObjectName="NameOfObjectToCompile" />
	</Target>
	<Target Name="UpdateWorkingModel">
		<UpdateWorkingModel />
	</Target>
	<Target Name="BuildOne">
		<BuildOne ObjectName="NameOfObjectToBuild" />
	</Target>
	<Target Name="BuildAll">
		<BuildAll />
	</Target>
</Project>

To run this script, you should use a command line like the following

	MSBuild /t::CreateKnowledgeBase;Import;OpenKnowledgeBase;Export;Reorganize;SpecifyAll;Generate;Compile;UpdateworkingModel;BuildOne;BuildAll 
TestAlPrimitives.msbuild

If you want to execute each function separately:

	MSBuild /t::CreateKnowledgeBase TestAlPrimitives.msbuild
MSBuild /t::OpenKnowledgeBase;Import TestAlPrimitives.msbuild
MSBuild /t::OpenKnowledgeBase;SpecifyAll TestAlPrimitives.msbuild
...

Building all objects of an existing Knowledge Base

<Project DefaultTargets="TestGenexus" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
   <Import Project="C:\Program Files\Artech\GeneXus\GeneXusX\Genexus.Tasks.targets" />
   <PropertyGroup>
      <KBPath>C:\MyKnowledgeBases\test</KBPath>
   </PropertyGroup>
   <Target Name="TestGenexus">
      <OpenKnowledgeBase Directory="$(KBPath)" />
      <SpecifyAll />
   </Target>
</Project>

Here is a sample: with it, you can create a KB, import an xpz, create a DB, build all & compile; all that just running a testall.bat.