Build future-proof enterprise applications

Don't be afraid of upgrades

How To Use It

In this walkthrough development environment setup and simple package developing is covered.

Steps for setting up development environment

Download the latest version of Rhetos source from https://github.com/Rhetos/Rhetos.

Check that you have fulfilled all the prerestiques mentioned in Readme.md, such as required .NET framework etc.

Build the source by executing Build.bat script or use VisualStudio (2010 or higher) to build tu build Rhetos.sln.

Prepare the web application

Since you will probably use web exposed features of Rhetos you have to prepare web application.

1. first way - use SetupRhetosServer.bat script and IIS Express (recommended for simple tasks)

SetupRhetosServer.bat is placed inside downloaded source folder \Source\Rhetos. Execute the script using Command Prompt with the following command-line arguments:

> SetupRhetosServer.bat <WebsiteName> <Port> <SqlServer> <DatabaseName>

SetupRhetosServer.bat command-line arguments:

  • WebsiteName - name of website in IISExpress config (choose any name, it is not directly related to URL of Rhetos web service)
  • Port - port that Rhetos web service will be listening to if using IIS Express (1234, for example)
  • SqlServer - Microsoft SQL Server on which there is/will be database for Rhetos server
  • DatabaseName - name of database that will Rhetos use, script will create database if it doesn't exist.

The script creates Database if it doesn't already exist, prepares configuration file for IIS Express site and configures few other necessary configuration files for Rhetos to function normally. Besides that, script deploys common packages and tests for common package (if nothing else is set to be deployed). At the end of execution, script displays how to start Rhetos server on IIS Express from command line.

2. second way is to use built-in features of Visual Studio (2010 or higher)

As start, open Visual Studio with Administrator privileges. Configure authentication for Rhetos project (under Server project group) to Windows authentication. If you are using IIS, be sure to additionally setup created web application (in IIS manager) so that the Rhetos application's Application Pool runs as a user with sufficient permissions.

3. third way is to manually create web application on IIS (7 or higher)

In this case, be aware of:

  • for best performance it is recommended to use newly created ApplicationPool. Set .NET version to 4.0. If using Rhetos v1.1 or older, set "Enable 32-Bit application" to true. Set Identity to a local admin user.
  • for Web application set Physical Path to \Source\Rhetos directory
  • for Web application disable Directory Browsing, for Authentication just enable Windows authentication and for Directory Path Credentials set account that is local admin

Prepare the database

Rhetos can use existing database as well as new one. Just set connection string in Rhetos\Source\Rhetos\bin\ConnectionStrings.config file (if it doesn't exists, rename Template.ConnectionStrings.config to it and use that one). If using SetupRhetosServer.bat, than you do not have to create database manually, that script will do it for you.

Rhetos will prepare database itself (DeployPackages.bat does that - it is called from ApplyPackages.bat or SetupRhetosServer.bat that are recommended way of using existing packages).

Defining packages that will be used

Once database and web application are prepared, it is time to define which packages are going to be used. Packages are being applied to Rhetos server using ApplyPackages.bat script from Rhetos\source\Rhetos\ApplyPackages.bat. That script reads ApplyPackages.txt for packages list (Template.ApplyPackages.txt is provided as example). ApplyPackages.txt is nothing more than list of directory paths to existing Rhetos packages.

For start and reference it is recommended to look at to source folder CommonConceptsTest\DslScripts, it has lot of examples for Common concepts prepared to be used in DslScripts.

When Rhetos server is configured, database prepared, packages applied and Rhetos server started, verify that everything works as expected:

  • start defined WebApplication (if IIS Express, than it is http://localhost:PORT/)
  • the page allows navigation to the interface for configuring permissions
  • now you are ready to write your own packages, concepts, DSL language and in the end complete application based on DSL language

For typical server applications we recommended to download an use RestGenerator Rhetos package. It will automatically generate REST API for all entities and other readable or writable data structures that are defined in a Rhetos application.

Creating your own application package

New features for Rhetos based solution can be developed and deploy in many ways, but right way is to create package and then use standard procedure with ApplyPackages.bat.

Create folder for your own package anywhere on the disk (for example C:\Rhetos\MyPackages\TestPackage)

For package definition, one file is required, everything else is optional:

  1. PackageInfo.xml - required - defines packages (you can modify CommonConcepts/PackageInfo.xml and copy it here)
  2. DslScripts - folder, optional, used for DslScripts that Rhetos will use for transforming (data tables, object model, report definition, generating claims, etc.)
  3. DataMigrations - folder, optional, used for data migration SQL scripts (data migration from one system to another, between versions or just populating default values - statuses etc.)
  4. Resources - folder, optional, used for report templates (word, excel, ...)
  5. Plugins - folder, optional, used for external references (plugin inside package)

Simple package in this example will contain one DslScript (and required PackageInfo.xml). For that purpose, create AddressBook.rhe file in DslScripts folder with following body:

Module AddressBook
{
    Entity Contact
    {
        ShortString Name;
        Date Birthday;
    }
}

Also create PackageInfo.xml from existing one (you can use PackageInfo.xml from CommonConcepts folder in Rhetos root folder) and setting Identifier to TestPackage.

With these steps, package is defined and ready to be applied to Rhetos server. It is done by adding path to newly created package in ApplyPackages.txt (add line C:\Rhetos\MyPackages\TestPackage in ApplyPackages.txt).

Run ApplyPackages.bat to apply package on Rhetos server and rerun Rhetos server (this is required if IIS Express is used). If any error occurs while deploying your package, it will be shown on console and logged in bin\DeployPackages.log file.

Just to verify that upon successful deployment everything is created as expected:

  1. Check if table AddressBook.Contact is created in your database.

If have also deployed RestGenerator Rhetos package, try using the generated web API:

  1. Check if new claims are listed in http://localhost:PORT/rest/Common/Claim.
  2. Retrieve current data from address book: http://localhost:PORT/rest/AddressBook/Contact.
  3. Try POST action to insert new data in AddressBook.Contact (if using Chrome, there is a simple extension for that task called "Advanced REST client"):
    • URL: http://localhost:PORT/rest/AddressBook/Contact
    • Action: POST
    • Payload: {"Name":"John"}
    • Content-Type: application/json
  4. Retrieve current data from address book http://localhost:PORT/rest/AddressBook/Contact. Check that the new contact entry is present.