MSBuild Tasks

Official Content

GeneXus MSBuild Tasks let you automate all about Knowledge Base building (i.e., automating import, specification, generation and compilation tasks among others). In a 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 the 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.

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 GeneXus 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: the user's 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 SQL Server, 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

The Import task is documented here.

OpenKnowledgeBase

The OpenKnowledgeBase task is documented here.

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

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

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

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 avoids 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”.

ExportKBInfo: include information about the Knowledge Base (KB Guid and source). Possible values "true" and "false". Default "true".

ExportAll: specifies to export the entire model and their active objects. 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" />

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" />

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

Samples

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

<BuildOne ObjectName="MyMainMenu" />

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 whether the object should be built as well; the default value is True. 

BuildCalled: indicates whether called objects should be built 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" />

RestoreRevision

Restore the specified object to the specified revision.

Syntax

<RestoreRevision Object=<"object type":"object name"> RevisionId=<"revision id"> />

CreateDatabase

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

Syntax

<CreateDatabase ExecuteCreate="true|false" />

Options

ExecuteCreate

Reorganize

Compiles and Executes the last Impact Data Base specified.

Syntax

<Reorganize />

SpecifyAll

Specifies all objects in a Knowledge Base, optionally forcing their 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" />

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)" />

Options

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" />

Options

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. 

SortByName: "true" to display table and index information ordered by name. Default: false. 

WriteDatabaseSchema

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

Syntax

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

Options

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" />

Options

Fix: determines if errors are fixed or not.

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)"/> 

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

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 brought. 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 the regional configuration of the machine. An independent format is suggested, i.e."yyyy-mm-dd hh:MM:ss".

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)" />

Options

EnvironmentName: is the name of an existing Environment. REQUIRED

Modules Handling

See Modules Distribution in GeneXus.

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

To process the result programmatically, check the CaptureOutput property.

Executing MSBuild Scripts

MSBuild scripts can be executed from the command line by invoking MSBuild.exe (stored in folder C:\WINDOWS\Microsoft.NET\Framework\v4.0 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 4.0 or higher. 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>
    <Target Name="RestoreRevision">
        <OpenKnowledgeBase Directory="$(KBPath)" />
        <RestoreRevision Object="ObjectType:ObjectName" RevisioID="RevisionId" /> 
    </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 an example: with it, you can create a KB, import an xpz, create a DB, build all & compile; all that just running a testall.bat.

See Also

Was this page helpful?
What Is This?
Your feedback about this content is important. Let us know what you think.