Rhetos.ComplexEntity 6.0.0

Rhetos.ComplexEntity

ComplexEntity is a DSL package (a plugin module) for Rhetos development platform. It provides functionality for manipulation with complex entities (such as master-detail) in same transaction. In order to work properly it introduces several concepts needed to implement this functionality - Function, Object and ListOf.

Contents:

1. Installation and configuration
2. ComplexStructure, Detail and Extension
   1. Using ComplexEntity in Domain Object Model
3. Function
4. Object and ListOf
5. How to contribute
   1. Building and testing the source code

See rhetos.org for more information on Rhetos.

Installation and configuration

Installing this package to a Rhetos application:

1. Add 'Rhetos.ComplexEntity' NuGet package, available at the NuGet.org on-line gallery.
2. Extend the Rhetos services configuration (at services.AddRhetosHost) with the ComplexEntity components: .AddComplexEntity()

ComplexStructure, Detail and Extension

ComplexStructure, Detail and Extension are DSL concepts which, in combination, provide functionality of retrieving and saving complex hierarchical data. That data can consist of several entities that have some kind of relation on to the other. Relationships that can be used are Detail and Extends. ComplexStructure replaces obsolete ComplexEntity DSL concept.

ComplexStructure concept creates a copy of the specified DataStructure and provides means to add complex hierarchical properties to it.

Detail concept creates ComplexStructure of the specified DataStructure and ListOf property to parent ComplexStructure.

Extension concept creates ComplexStructure of the specified DataStructure and Object property to parent ComplexStructure.

CreateGet concept creates a Function for retrieving an instance of specified ComplexStructure. Input parameter is ID of 'master' entity. Additionally, concept AfterGet is provided that allows you to insert your code before returning result for postprocess purposes like filling additional data (see example bellow).

CreateSave concept creates Function for saving an instance of specified ComplexStructure, and also creates CreateGet. Input parameter is specified ComplexStructure itself. Output parameter is also the same ComplexStructure with updated propagated ID-s throughout the object hierarchy. Additionally, concepts BeforeSave and AfterSave are provided that allows you to insert your code before and after save sequence for preprocess and postprocess purposes.

Example:

Module ComplexStructures
{
    Entity MasterEntity
    {
        ShortString Title;
    }

    Entity ExtensionEntity
    {
        Extends ComplexStructures.MasterEntity;
        ShortString OrderNumber;
    }

    Entity DetailEntity
    {
        Reference MasterEntity { Detail; }
        ShortString Description;
    }

    Entity SubDetailEntity
    {
        Reference DetailEntity { Detail; }
        ShortString PartNumber;
    }


    ComplexStructure MasterComplex ComplexStructures.MasterEntity
    {
        Integer DetailCount;
        
        Detail ComplexStructures.DetailEntity Details    //created ComplexStructure name is MasterDetailsComplex
        {
            Detail ComplexStructures.SubDetailEntity Details;    //created ComplexStructure name is MasterDetailsDetailsComplex
        }

        Extension ComplexStructures.ExtensionEntity Extension;    //created ComplexStructure name is MasterExtensionComplex

        Bool PerformPostValidation;

        CreateGet
        {
            AfterGet 'FillAdditionalData'
            '
                root.DetailCount = root.Details.Count;
            ';
        }
        CreateSave    //created Function name for save is MasterComplexSave, and for get is MasterComplexGet
        {
            BeforeSave ValidateData
            '
                if (parameters.Item.Details == null || !parameters.Item.Details.Any())
                    throw new Rhetos.UserException("Entity must have at least one detail.");
            ';

            AfterSave SomeAfterSaveValidation
            '
                if (parameters.Item.PerformPostValidation.GetValueOrDefault())
                {
                    // some after save optional validation
                    // throw new Rhetos.UserException("Some validation description."); - this exception rollbacks entire transaction, nothing is saved
                }
            ';
        }
    }
}

Using ComplexEntity in Domain Object Model

After reading How to execute examples you can try this example of saving and loading with ComplexEntity that uses DSL described above:

void Main()
{
    ConsoleLogger.MinLevel = EventType.Info; // Use "Trace" for more detailed log.
    var rhetosServerPath = Path.GetDirectoryName(Util.CurrentQueryPath);
    Directory.SetCurrentDirectory(rhetosServerPath);
    // Set commitChanges parameter to COMMIT or ROLLBACK the data changes.
    using (var container = new RhetosTestContainer(commitChanges: false))
    {
        var context = container.Resolve<Common.ExecutionContext>();

        var complex = new ComplexStructures.MasterComplex
        {
            Title = "My first complex entity",
            Details = new List<ComplexStructures.MasterDetailsComplex>
            {
                new ComplexStructures.MasterDetailsComplex {Description = "Detail a"},
                new ComplexStructures.MasterDetailsComplex
                {
                    Description = "Detail b",
                    Details = new List<ComplexStructures.MasterDetailsDetailsComplex>
                    {
                        new ComplexStructures.MasterDetailsDetailsComplex { PartNumber = "the part number 1" },
                        new ComplexStructures.MasterDetailsDetailsComplex { PartNumber = "the part number 2" }
                    }
                }
            },
            Extension = new ComplexStructures.MasterExtensionComplex { OrderNumber = "123"},
            PerformPostValidation = false
        };

        //save complex entity
        var result = context.Repository.ComplexStructures.MasterComplexSave.Execute(new ComplexStructures.MasterComplexSave { Item = complex });

        //load complex entity
        var loaded = context.Repository.ComplexStructures.MasterComplexGet.Execute(new ComplexStructures.MasterComplexGet { ID = result.ID });
    }
}

Function

The Function concept allows adding custom web API methods to the Rhetos REST service.

It is similar to Action concept, except it allows you to return some result. Additional parameter specifies type of return value. For example:

Module Functions
{
    Entity Post
    {
      ShortString Title;
      LongString Content;
    }

    Function CreateNewPost Functions.Post //returns instance of type Functions.Post
    '(parameter, repository, userInfo) =>
    {
        var content = parameter.Content ?? "Default Content";

        var post = new Functions.Post
        {
          Title = parameter.Title,
          Content = content,
        };

        repository.Functions.Post.Insert(post);

        return post;
    }'
    {
        ShortString Title;
        LongString Content;
    }
}

Object and ListOf

Object is a DSL concept which allows you to define a DataStructure property that is a reference type of another DataStructure.

ListOf is DSL concept which allows you to define a DataStructure property that is a list of type of another DataStructure or simple property (ShortString, Integer, etc.). In C# Domain Object Model it is represented as List<T>.

Example:

Module Functions
{
    Entity Post
    {
        ShortString Title;
        LongString Content;
    }

    Parameter ReturnValue
    {
        ShortString SomeValue;
        Object Functions.Post Post;
        ListOf Functions.Post AdditionalPosts;
        ListOf ShortString Contributors;
    }
}

How to contribute

Contributions are very welcome. The easiest way is to fork this repo, and then make a pull request from your fork. The first time you make a pull request, you may be asked to sign a Contributor Agreement. For more info see How to Contribute on Rhetos wiki.

Building and testing the source code

• Note: This package is already available at the NuGet.org online gallery. You don't need to build it from source in order to use it in your application.
• To build the package from source, run Clean.bat, Build.bat and Test.bat.
• For the test script to work, you need to create an empty database and a settings file test\Rhetos.ComplexEntity.TestApp\rhetos-app.local.settings.json with the database connection string (configuration key "ConnectionStrings:RhetosConnectionString").
• The build output is a NuGet package in the "Install" subfolder.