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.

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.

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.

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.

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.

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.

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.

Deploy

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.

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.