Skip to content

Quick start

After installing the Entity Services CLI tool for the first time, check that it’s installed by running:

es-builder

Authenticate

Before using any of the EntityServices CLI commands, you need to sign in with es-builder login

1. Run the login command

   es-builder login

If the CLI can open your default browser, it will initiate the authorization code flow and open the default browser to load an Entity Services sign-in page.

2. Sign in with your account credentials in the browser.

Use the provided credentials to log in to the Entity Services App Builder tool.

Configure the solution

Entity Services App Builder creates fully functional C# source code based on the configuration of the solution and entities. When the the build process is started, the es-builder tool will by default search for all files with .yml extension in current folder and subfolders. This feature allows separating configuration in multiple files and subfolders. For instance, entities configurations may be placed into a subfolder based on the group that they belong to.

Here is an example of a basic solution configuration and one entity with few properties. This documentation has separate chapters about solution configuration and entities.

solutionName: "Axellon.Demo"
dataApi:
    entityGroups:
      - group: default
        enableHistory: true

        readComponents:
          - type: MongoDbComponent
        writeComponents:
          - type: ValidationComponent
          - type: MongoDbComponent
        endpoints:
          - type: WebApiEndpoint

entities:
- entity: Horse
  pluralName: Horses
  properties:
  - Id:
      type: uuid
      description: The unique identifier for the horse
  - Name:
      type: string
      maxLength: 100
      description: The name of the horse
  - Age:
      type: integer
      description: The age of the horse
  - IsPet:
      type: boolean
      nullable: True
      description: Indicates if the horse is a pet
  - PowerOutput:
      type: number
      minValue: 1.8
      maxValue: 1000000.2
      defaultValue: 1.9
      description: The power output of the reactor in megawatts
      precision: 18
      scale: 2
      format: decimal

For other configuration examples visit Examples section.

Build solution

Build process is started with build command:

es-builder build

When the build command is started, it will use configuration file(s), build the solution and store it in a defined location. By default, it will download the created source code to the current folder.

Create Cloud Storage

The example of the configuration above requires MongoDB database. The easiest way to get started is by using Entity Services CLI to create MongoDB database in Azure.

The following command will create Azure CosmosDB account, Mongo database and the collection for our entities. Change to parameters to your preferences.

es-builder deploy azure-mongodb --resourcegroup <<resource-group>> --location <<location-value>> --account <<account-value>> --database <<database-name>> --collections "Entity_A,Entity_B"

The command will add the connection string to your environment variable that the generated solution will use.

If the generated solution is opened in your development IDE, such as Visual Studio, make sure to reopen the IDE so that the environment variable generated by the above command is loaded into it.

Build and Start the application

Set WebApi project as a Startup Project.

Build and start the application.

Open API Web UI

Based on the default settings in app.settings, upon starting the WebApi project, the web browser will be automatically opened. Add the route /interactive-docs to the URL to navigate to OpenAPI UI.

Http files

WebApi project contains the folder HttpEndpoints with .http files. They aim to allow the execution of HTTP commands via Visual Studio Code extension REST Client. Files can be used in Visual Studio or Rider environments, with minimal adjustments.

Back to top