Generator only operations

Hide Navigation Pane

Generator only operations

Previous topic Next topic No directory for this topic  

Generator only operations

Previous topic Next topic Topic directory requires JavaScript JavaScript is required for the print function Mail us feedback on this topic!  

The operations listed in this topic are available only in the Persistate Generator application.  They are in the  province of application developers and are concerned with the business of package creation and code generation.

Environment operation group

This operation group concerns operations which are performed on an Environment target object.  The operations can be found in the Environment main menu and right click context menu.  These will be available if the Environment Form or the Environment Grid is selected.

The environment operation group contains another operation, Import Package, which is also available in the Configurator application.  See Common operations for details of this one.

Many of the operations described here are used in the Creating and running the Device Network demonstration walkthrough, so there is a good place to look for examples of using them.

Create package

This operation creates a brand new Package in the target environment.  Use this to create a new Persistate application.  Before you execute this operation, make sure Visual Studio has no solution loaded.  When you execute this operation, Persistate displays a dialogue box asking you to enter parameters for the new package.

The parameters required are mostly intuitive.  If you have not yet written a definition file for the new package, leave Import Definition File clear, and a blank one will be created for you in the Model project.  The Package Name will be completed automatically from the display name.  Note that for now C# is the only language supported, and Persistate can create only a Desktop UI.  When you have completed all the parameters, click Create.

Persistate now creates a new solution in Visual Studio.  The solution will have four projects, one each for the Model, Controller and User Interface, and a fourth which is a StartUp project producing an executable file for starting the package in stand-alone mode.  The projects are given all appropriate references to each other and to the Persistate run time libraries.

Once the solution and projects have been created, the new Package object is created and added to the Environment.ProductPackages collection, and the Package Form is displayed.

Recreate package

Use this operation when you have previously created a package, but for one reason or another, you have deleted it from persistent storage, or you have deleted the root database or the database containing package.

This operation recreates the package from a serialised package file called <package name>.ser created by the Deploy operation.  This file contains all the metadata and configurative objects.  This means that for example all the layouts you defined, and which correspond with any generated classes you may already have created, will be restored as they were.

This operation gives you the ability to delete a Package object from persistent storage, and then re-create it as it was.  This gives you a certain amount of agility during the development process, allowing you to start from scratch with a new root database, but not lose the work you have done so far.  The only thing to remember is to always execute Deploy after you make any changes such as creating or modifying layouts or configurative objects.

Layout operation group

This operation group concerns operations which are performed on an Layout target object.  The operations can be found in the Layout main menu and right click context menu.  These will be available if the Layout Form or the Layout Grid is selected.

Generate class

This operation generates or regenerates the .Net class for the target Layout object.  The class is created or updated in the package's Desktop user interface project.  Persistate asks you for confirmation before doing the work.  The class is generated using any layout style set for the layout, or if this is not set, the default layout style of the containing package.

If the class does not already exist, then it is generated with all controls arranged vertically, and separated by the LayoutStyle.ControlVerticalSeparation value.  You will normally want to open the generated class in the Visual Studio form designer and move and resize the controls into a more suitable arrangement.  There is nothing further you need to do - binding is already set appropriately.

If the class already exists, and you are updating it, say because you have added a member and placement, then Persistate reads the existing class and keeps any property values you have set for existing controls, including the location and size properties, and also any non generated controls that you may have added manually.  Note that if you delete a class member, and regenerate a class layout, you will have to delete any control that was bound to the deleted member manually.

Future Enhancement

For the moment, Persistate generates Windows Forms classes only.  Future versions of Persistate will generate other types of user interface.  Exactly which is yet to be decided but candidates are HTML4, HTML5, XAML and Flash, as well as mobile platforms Windows, iOS and Android.

Update placements

This operation updates the Layout.Placements collection to reflect any changes in the layout's parent object class's ObjectClass.Members collection.  There is one placement in the layout per member in the object class, and this operation maintains that parity.

Future Enhancement

This is perhaps not an ideal situation.  It is reasonable to wish more than one placement per member.  For example a number might be portrayed by both a slider and a number box on the same form.  For the moment the New operation is not available for placements, but this may change in a future version of Persistate.

This operation is executed by Persistate whenever a new layout is created for an object class.  Execute this operation whenever you add a member to or remove a member from an object class definition after the layout is created.

Package operation group

This operation group concerns operations which are performed on an Package target object.  The operations can be found in the Package main menu and right click context menu.  These will be available if the Package Form or a Package Grid is selected.

Generate default layouts

This operation generates a full set of default layouts for the object classes that you have defined in your package.  The algorithm used to decide which layouts to generate takes into account the use of each object class.  For example, if there are any collections of several object of a given class, then a grid layout is generated for that class.  If there are any collections of many such objects, then a lookup layout is generated for the class.  A tree layout is generated for each singleton class.

This operation is one you will want to execute once you have completed and processed your definition file successfully.  You can execute this operation directly, or there is also an option in the dialogue box put up by the Process definitions operation which will cause that operation to execute this one.

This operation makes a fair stab at generating appropriate layouts for your package.  However, it is a very good idea to go through all the generated layouts and make sure that they fulfil your requirements, before you generate the classes.  For example, for contained collections, Persistate will most often generate a grid access button.  You may want to replace that with a sub-grid, to show the collection within the form.

Once you have modified the default layouts to your liking, then the Process Definitions operation has an option to generate classes for all the layouts within the package, or you can generate classes for individual layouts using the Generate class operation.

Process definitions

This operation processes your package definition file, and creates the metadata objects (ObjectClass, DataClass, Layout, Placement, etc.) for your package. If there are any syntax errors or semantic errors in your definition file, Persistate creates an error.txt file and opens it in the Visual Studio editor.

Future Enhancement

This arrangement is somewhat primitive.  A future version of Persistate will have an integrated editor for definition files in the IDE, with full syntax highlighting.  Also, the current definition file parser does not handle syntax errors particularly well.  One such error will cause many more following ones.  The best advice is to deal with the first error, and reprocess the file.  This problem will be fixed.

As well as processing the definition file, this operation can perform a number of optional generation functions.  These are controlled by a small dialogue box that is displayed - set the checkbox to perform the function.  The functions are as follows.

Generate Model Classes.  This function generates the .Net classes and structs corresponding to the object classes, data classes and view classes in the definition file, and puts them in the package's Model project.  For object classes and view classes, a .Net class is always generated.  For data classes, a .Net struct is generated only for multi-value types.  This also generates the The class with properties allowing access to your defined singletons.

Each generated class or struct is in two partial files.  The <class name>.cs file is initially empty, and you develop the class or struct using this file.  The <class name>.gen.cs file contains all the generated fields, properties and methods, and is recreated every time you choose this option.  This file is found under the first in the Visual Studio solution explorer.

Generate Operation Classes.  This function generates two methods for each operation in the definition file.  The methods are put into two static classes generated for each operation group.  Both generated class files have the same name - <operation group name>Operations.cs - one being in the Controller project and the other in the Desktop (user interface) project.

The class generated in the Desktop project contains a <operation name>Presence method for each operation in the group.  This method is called by the Persistate user interface infrastructure to determine whether the operation should be enabled, disabled or invisible at that time, and to give the operation a tooltip.  These methods are generally called on the Application.Idle event.

The method generated to execute the operation is called Execute<operation name> and is put into the class in the Controller project, except for operations defined as user interface operations which are put in the Desktop project class alongside the "presence" method.   When generated, these methods are just stubs which return a 'not implemented' warning.  You write the code for your application in these methods.

Generate Default Layouts. This function generates a full set of default layouts for the object classes that you have defined in your package.  It does this simply by calling the Generate default layouts operation.
Generate Desktop UI Classes.  This function generates the .Net class implementing every layout within the package.  This performs the same function as the Generate class operation for each defined layout, so see there for details.
Update Databases.  This function updates the tables, indexes, constraints, views and stored procedures in one or more databases so that instances of the objects and collections in the package can be stored in that database.  If any selected database had not previously been targeted by this package, then it is also added to the Package.TargetDatabases collection.


If you modify the definition file, and execute this function, then be aware that in some circumstances you may lose data in the database.  For example, if you rename a property of an object class, Persistate will delete the field with the old name and create a new one.  Also, if you add values to a multi-value data class, then the meanings of existing values in the database may change.

Create test data

This operation fills the containment tree for the package with test data.  The data is created in your development environment - the environment containing the package in its ProductPackages collection.  This operation puts up a dialogue box where you can alter the parameters used to create the data.

By default, this uses the Persistent.WriteTestData and Persistent.WriteTestAssociations methods to create the test data.  You can override these to provide test data more suited to your application.  See the API documentation of these methods for more details.


You use this operation to distribute your package.  There are three ways in which packages can be distributed, all of which are handled by the Deploy operation.

They can be distributed directly to a Viewer from a Server running in the same Domain in which they are developed.  To handle this, the Deploy operation stores the assemblies for the modules making up the Package in the persistent tree and they are distributed from there.

Future Enhancement

For now, Persistate stores only the code for the projects it creates, so all of your application code must be in one of these projects.  Also, there is no versioning of the assemblies.  On or before version 1.0, Persistate will have much more complete handling of package deployment to servers and viewers.

They can be distributed in the normal way, using a setup project to build an executable or .MSI file.  To handle this, the Deploy operation saves the metadata and configurative data for your package into a file.  The file will be called <package name>.ser and will be put in the package Model project.  The file is actually part of the project, and included in the Model .dll file as an embedded resource.  When the installed package is run in stand-alone mode for the first time, a database is created and all the objects in the embedded file are extracted and stored in the database, and the application is immediately ready to run.

The metadata in the <package name>.ser file is comprised of all the ObjectClass, DataClass, Layout, Placement and all the other objects created by the Process definitions operation, as well as the developer (for layouts, etc) for the package.  It contains sufficient information to restore the Package object and all objects in its containment tree to exactly their state at the time this operation is called.  This file is also used by the Recreate Package operation.

The configurative data in the file is comprised of any configurative singletons along with the configurative containment tree under each.  This is simply the containment tree with all non configurative objects filtered out.  Configurative classes are intended to be used for things like lookup tables - objects that you want to be distributed with the application.  In our Library package, the Genre class is configurative, as genres are applicable to any Library installation.

They can be imported into a domain other than the one in which they were developed.  To handle this, the Deploy operation creates a file called <package name>_Deploy.ser .  This is created in the package's solution folder and does not belong to any project.  This is similar to the <package name>.ser file (see above) but also contains the assemblies which were stored in the persistent tree.   These files are used to import the package into another domain using the Import package operation.