This project is read-only.

Zen4Sync POCO Generation



Overview

Zen4Sync uses WCF (Windows Communication Foundation) communication between Orchestrator and Test Server(s) (you can of course configure the WCF communications).
The Orchestrator does not transmit Entity Framework entities through WCF : it transmits POCO (Plain Old CLR Object) equivalents of the entities.
These POCOs are automatically generated from the tables in the Zen4SyncRepository database (the database created and used by Zen4Sync in order to work).
The code generation is achieved using OlyMars

POCO generation rules

The POCO generation obeys the following rules :
  • A table becomes a POCO (i.e. a class)
  • A column (non foreign key) becomes a property whose type is the C# equivalent of its SQL type
  • A foreign key becomes a property whose type can be the POCO generated for the foreign table
  • A POCO can contain a collection of other POCO

The code generation makes extensive use of the SQL Server extended properties.

Table to POCO

Not all tables of Zen4SyncRepository are transformed into POCOs.
Only tables selected in OlyMars are turned into POCOs. (see how to customize the POCO generation to know how to include new tables in the selection).
Each selected table will lead to the creation of its equivalent POCO having the following properties :
  • The namespace of the POCO is the schema of the table prefixed by Zen4SyncPOCO.POCO
  • The POCO is a public partial class

Example : The POCO equivalent of the table [Scenario].[activity]
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace Zen4SyncPOCO.POCO.Scenario
{
	///<summary>
	/// Class generated using OlyMars
	///</summary>
	public partial class Activity
	{
		// properties, see the following sections for details
	}
}

Column (non foreign key) to property

A simple column (i.e. not a foreign key) will be turned into an public get; set; property.
The type of the property is the C# equivalent of the SQL type of the column.
The column will be included into the POCO only if it owns an extended property called POCO_Include whose value is set to True.
If the extended property is not present or its value is not True, the column will not be included into the POCO.

Example : Generated properties for the columns of the table [Scenario].[activity]
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace Zen4SyncPOCO.POCO.Scenario
{
	///<summary>
	/// Class generated using OlyMars
	///</summary>
	public partial class Activity
	{
		public System.Guid activity_id { get; set; }
		public System.Guid activity_activityItemId { get; set; }
		public System.Int32 activity_executionOrder { get; set; }
		public System.Int32 activity_preWaitingTimeInSeconds { get; set; }
		public System.Int32 activity_postWaitingTimeInSeconds { get; set; }
		
		// foreign key properties, see the following sections for details
	}
}

Foreign key to property

A column which is a foreign key leads to the creation of a property whose type can be the POCO equivalent of the foreign table.
Note that since the foreign key is a column, it must own the POCO_Include extended property set to True to be included into the POCO.

Example : Navigation properties for foreign keys of the table [Scenario].[activity]
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace Zen4SyncPOCO.POCO.Scenario
{
	///<summary>
	/// Class generated using OlyMars
	///</summary>
	public partial class Activity
	{
		public System.Guid activity_id { get; set; }
		public System.Guid activity_activityItemId { get; set; }
		public System.Int32 activity_executionOrder { get; set; }
		public System.Int32 activity_preWaitingTimeInSeconds { get; set; }
		public System.Int32 activity_postWaitingTimeInSeconds { get; set; }

		public Zen4SyncPOCO.POCO.Scenario.TestScenario activity_testScenario { get; set; }
		public Zen4SyncPOCO.POCO.Scenario.ActivityType activity_activityType { get; set; }
	}
}

Note : If you want the property's type to be the .NET equivalent of the column type (as opposed to the type of the foreign POCO), you can use the extended property POCO_GenerateComplexProperty on the column and set its value to False.

Example : Generated POCO for the table [Admin].[TestSession] with non-complex property for foreign keys.
namespace Zen4SyncPOCO.POCO.Admin
{
	///<summary>
	/// Class generated on 21/04/2011 12:19:50 using OlyMars.
	///</summary>
	public partial class TestSession
	{
		public System.Guid testSession_id { get; set; }
		public System.String testSession_name { get; set; }
		public System.Unknown->[sys].[datetimeoffset] testSession_createdOn { get; set; }

		/* Note that even if testSession_testSessionCategoryId is a foreign key
		 * towards the table testSessionCategory, its type is not TestSessionCategory.
		 * This is because the testSession_testSessionCategoryId column owns the extended
		 * property "POCO_GenerateComplexProperty" with a value set to "False". */
		public System.Guid testSession_testSessionCategoryId { get; set; }

		public System.Guid testSession_testSessionStateId { get; set; }
	}
}

Collection property

Sometimes not only we want a foreign key to become a property, but we also want a collection of POCOs in the foreign table.
For instance, table [Scenario].[activity] owns a foreign key towards [Scenario].[testScenario] and we want two things :
  • A TestScenario property into Activity POCO (see previous example)
  • A List<Activity> property into TestScenario POCO

The second point is easily achieved by adding an extended property on the [Scenario].[testScenario] table : POCO_GeneratedCollections.
The value of this extended property must follow the following format :
  • A collection property is generated for every duet of colon-separated values : PropertyName:ForeignTableSchema.ForeignTableName
  • You can generate as many collections as needed by combining duets. Each duet is separated of the next one using semicolon : MyCollectionProperty1:TableSchema.tableName1;MyCollectionProperty2:TableSchema.tableName2

For instance, if we want a colllection of Activity called testScenario_activities in the TestScenario POCO we had the POCO_GeneratedCollections extended property on the [Scenario].[testScenario] table and set its value to :
testScenario_activities:Scenario.activity

This leads to the creation of testScenario_activities property in the TestScenario POCO :
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace Zen4SyncPOCO.POCO.Scenario
{
	///<summary>
	/// Class generated using OlyMars
	///</summary>
	public partial class TestScenario
	{
		public System.Guid testScenario_id { get; set; }
		public System.String testScenario_name { get; set; }
		public List<Zen4SyncPOCO.POCO.Scenario.Activity> testScenario_activities { get; set; }
	}
}

Extended Properties recap

Extended Property name Extended Property target Accepted values Extended Property effects
POCO_Include Column True False If True, the column will be converted into a public property in the generated POCO.
POCO_GenerateComplexProperty Column (foreign key) True False If False, the generated property's type will be the .NET equivalent of the column's type (as opposed to the type of the POCO generated for the foreign table).
POCO_GeneratedCollections Table PropertyName:ForeignTableSchema.ForeignTableName[;...] Generates a collection property for every duet of colon-separated values.


Use OlyMars to generate POCOs

There are two things you can do with OlyMars in the Zen4Sync context : generate POCOs and modify the POCO generation template.
For both things you'll need to download OlyMars and run it at least once to set it up.

Set up OlyMars for the first time

Create OlyMars database

First download OlyMars from the OlyMars website (currently v. 1.5)
What you need to do is to create OlyMars working database in your SQL Server instance.
Your SQL Server instance has to be named SQL2008R2 and use Integrated Security for the POCO generation to work.
  • Start by running OlyMars (SQLCodeGenDotNet.exe in the OlyMars directory).
  • On the first window, click Create or upgrade the repository database.

228198

This opens a new window you must fill as follow :
  • Create a new Database : type OlyMars and click Create
  • Pick up an existing database : select OlyMars

228219

Then click the Install button.

Import Zen4Sync group in OlyMars

Now that the OlyMars database has been created, you need to import the Zen4Sync group in OlyMars.
This group contains the templates used to generate POCOs.

To import the Zen4Sync group :
  • Get the Zen4Sync.xml file which is on Zen4Sync TFS under \Main\Tools\Zen4SyncTools\POCOGeneratorOlyMars\OlyMarsImport\Group
  • In OlyMars menu, go to Main > Repository (or press Ctrl + R)
228213
  • Right-click on Groups and select Import a group
  • Select the Zen4Sync.xml file
  • Click Import on the next window
228214

Once the Zen4Sync group is imported, you'll need to import the Extended Properties used for the POCO generation.

Import Extended Properties

To import the Extended Properties :
  • Get the file called Zen4SyncRepository Extended Properties.xml under \Main\Tools\Zen4SyncTools\POCOGeneratorOlyMars\OlyMarsImport\ExtendedProperties
  • Open OlyMars and use the menu to navigate to Main > Connect to a database (or press Ctrl + D)
233410
  • Press Refresh, select Zen4SyncRepository and press OK
  • Use the menu to navigate to Main > Database extended properties (or press Ctrl + O)
233411
  • Right-click on Zen4SyncRepository and select Import some extended properties
  • Locate the Zen4SyncRepository Extended Properties.xml and click Ouvrir
233412
  • Only check Tables and Table columns and triggers then click Ok.

Now the needed Extended Properties are imported, you're ready to generate code.

Generate POCOs from Visual Studio with OlyMars

Before trying to generate POCOs, make sure you've properly setup OlyMars.
To generate POCOs, all you need to do is use the POCOGeneratorOlyMars project which is in the Zen4SyncTools solution on the Zen4Sync TFS.
The Zen4SyncTools solution is under Main\Tools\Zen4SyncTools.
Open the solution and find the POCOGeneratorOlyMars project.

Once this is done, you can generate POCOs by executing "Zen4Sync POCO Generator batch.bat" (the file is under CodeGeneration\POCO) from a command prompt.

The .bat file runs the POCO generation.

Customize the Zen4Sync POCO generation

There are several ways in which you can customize the POCO generation

Include new tables in the POCO generation

To include new tables in the POCO generation (i.e. these tables will be turned into POCOs), open the Zen4Sync POCO Generator batch.xml file (the file is under CodeGeneration\POCO) in the POCOGeneratorOlyMars project.

Add a new Table node under the node BatchMode/WorkingDatabase/Tables.

Type the table name in the Name attribute of the new Table node.

<Table Name="[table_schema].[table_name]" />

Change the output directory of the POCOs

To change the output directory of the POCOs, open the Zen4Sync POCO Generator batch.xml file (the file is under CodeGeneration\POCO) in the POCOGeneratorOlyMars project.
Modify the OutputDirectory attribute of the BatchMode node.
Note : The output directory is relative to the OlyMarsBin directory of the project. It is not relative to the root directory of the project.

Change the POCO generation template

TODO

Last edited Apr 28, 2011 at 12:35 PM by Christophe_, version 75

Comments

No comments yet.