Harmony Core CLI Tool - Synergex/HarmonyCore GitHub Wiki

Introduction to the Harmony Core CLI Tool

The Harmony Core CLI Tool is a utility for managing, extending, and regenerating code for Harmony Core solutions. It is a replacement for regen.bat and provides a UI for many common Harmony Core tasks, such as:

Configuring code generation options
Regenerating Harmony Core components
Managing OData settings and authentication
Adding Traditional Bridge projects

Requirements

.NET 8 SDK - Verify by running:
```
dotnet --version
```
A Harmony Core solution. The CLI Tool can be run only in the solution directory for a Harmony Core solution.

Installing and Updating

To see if the CLI Tool is installed, enter the following command at a terminal prompt:

dotnet tool list -g

To install the CLI Tool, enter:

dotnet tool install -g Harmony.Core.CliTool

To update an existing installation, enter:

dotnet tool update -g Harmony.Core.CliTool

Launching the GUI for the CLI Tool

Open a terminal and navigate to a directory containing a Harmony Core solution file (.sln). Then enter:

harmonycore gui

After a brief "Loading Solution" message, the Harmony Core CLI Tool GUI opens with a menu and five tabs: Solution, OData, Structures, Traditional Bridge, and Interfaces.

Note: The CLI Tool requires only a .sln file to launch. However, to load settings it requires either an existing Harmony.Core.CodeGen.json file or a regen.bat file whose settings it can import to create the Harmony.Core.CodeGen.json file for the solution. (See Settings File and Persistence below for more information.) One of these must be in the solution root or the GUI will prompt you to select a JSON file. If you don't select one, the load will fail.

Settings File and Persistence

When you first run harmonycore gui in a solution directory, the CLI Tool creates a Harmony.Core.CodeGen.json file at the root of the solution (typically by importing settings from regen.bat). This JSON file is the means for persisting the CLI Tool's settings and options. Note the following:

Changes made in the CLI Tool are not until you select an option that saves them. Use File > Save to write the current settings to Harmony.Core.CodeGen.json. CodeGen > Regen automatically saves the current settings before regenerating, so changes are included in the regen even if you didn't manually run File > Save first. However, if you close the CLI Tool without saving (or without running Regen), your changes will be lost.
When you create Harmony Core solution from one of the Harmony Core templates, the solution will have a regen.bat file (with initial settings) in the solution folder. This file will be used to create the Harmony.Core.CodeGen.json file the first time the CLI Tool GUI is launched.

What You Can Do with the CLI Tool

Using the CLI Tool, you can:

Enable OData support and generate related code (models, controllers, service files). See Enabling OData Support for more information.
Generate and manage sample data. See Generating Harmony Core Sample Data for more information.
Add OData endpoints with query and relation expansion support. See Entity Collection Endpoints, Single Entity Endpoints, OData Query Support, Alternate Key Endpoints, and Expanding Relations.
Generate Postman tests. See Generating and Using Postman Tests.
Add CRUD endpoint support (Create, Upsert, Patch, Delete). See Adding a Primary Key Factory, Adding Create Endpoints, Adding Upsert Endpoints, Adding Patch Endpoints, and Adding Delete Endpoints.
Implement authentication. See Tutorial 3: Authentication via Custom Code.
Add a Traditional Bridge project. See Tutorial 4: Implementing Traditional Bridge.

GUI Overview

The CLI Tool GUI has the following menus:

File — Save the current customization file, import regen.bat settings, or validate configuration scripts.
Search — Search for settings on the current screen.
CodeGen — Regenerate code for the current solution or synchronize files with the specified options.
Features — Add Traditional Bridge projects, Synergy Method Catalogs (SMCs), or unit tests.

The CLI Tool GUI has the following tabbed screens:

Solution — Solution-level settings such as folder locations and namespaces.
OData — Authentication (OAuth), API, and service configuration.
Structures — Repository structures and related settings.
Traditional Bridge — Traditional Bridge settings, SMC configuration, and unit test options.
Interfaces — Interface definitions and related settings for Traditional Bridge.