Hop til hovedindhold

D230 Developer Guide

Document status35 - Reviewed

To make it easy to onboard developers and to ensure a uniform way of working, a Developer Guide must tell how it will be possible to contribute to the solution. The guide must answer how a development environment is set up and what technical prerequisites must be met to make it happen. Any requirements for the preparation and storage of code must also be described in the Developer Guide.

Setup a local development environment​

This section describes setting up a running local environment on a developer's machine. Before the developer can follow this guide, they must be added to the "Energy Connect 3 team" in the Azure DevOps project.

  1. Install prerequisites:

  2. Clone our repository using git.

    • If you do this through Rider or VS, they should include/install Git semiautomatically, if it is missing.

  3. Start Docker Desktop.

  4. In PowerShell at the repository root, run:

    .\dev.ps1 setup

    The setup command configures FellowX authentication, starts PostgreSQL, applies ECC and DMC migrations, generates frontend models and local development data, and starts the default Docker Compose stack. Linked worktrees automatically receive isolated settings and ports.

  5. Open <http://localhost:4200> in a browser to open the application. You will be redirected to the dev login page where you can select your user and roles (see Security during development.

All local development commands are accessed through .\dev.ps1. Run .\dev.ps1 help to list available commands or .\dev.ps1 help <command> for details about a specific command.

To skip selected setup steps, use the corresponding switches:

.\dev.ps1 setup -SkipMigrations -SkipFrontendModels -SkipDevData -SkipDocker

The IDE Docker Compose Fast Mode remains the default workflow for running and debugging from Visual Studio or Rider. Developers who need direct terminal Compose control can use the stack started by .\dev.ps1 setup.

FellowX authentication​

Run .\dev.ps1 auth to configure or refresh authentication for the FellowX Azure Artifacts feed. The command tries Git Credential Manager first. If it cannot obtain a credential, it securely prompts for an Azure DevOps PAT with Packaging Read scope. For noninteractive use, set AZURE_DEVOPS_PAT.

Credentials are not passed as command-line arguments. If package restore reports missing or expired Azure Artifacts authentication, rerun .\dev.ps1 auth and retry.

Azure Portal Access​

For access to resources on Azure Portal, the developers need to request the following from IT:

  • A "Proactive Hosting" account.
  • Invitation for the "Proactive Hosting" account to the Directory "ProActive Datahub".
  • Request "Contributer" access to "Energy Connect" subscription from IT.
  • VPN access for the "Proactive Hosting" account to the "hub-dev", "hub-test" and (if needed) "hub-prod" CISCO VPN groups.

The VPN client needed to connect can be found here: vpn.proactive.hosting - log in with the "Proactive Hosting" account, select "hub-test" and you will be presented with a download option. After installing, you can log in with your proactive.hosting credentials.

How to work with the solution​

The following sections describe some of the common patterns that are useful to know during development.

Generating test data​

Local development data is generated during .\dev.ps1 setup. To regenerate it independently, run:

.\dev.ps1 db seed

Select a data category with --category, for example:

.\dev.ps1 db seed --category grid-loss --reset

Use .\dev.ps1 db seed --list to list available categories and .\dev.ps1 db seed --help to see all options.

Checking errors in backend/frontend​

  • Backend build errors - Check your IDE output (Rider / Visual Studio).
  • Frontend build errors - Check the client-dev container logs in Docker Desktop.
  • Backend runtime errors - Check the local log aggregation tool, Seq, at <http://localhost:5341>.
  • Frontend runtime errors - Check the browser DevTools Console and Network tab.

Running backend jobs​

We use Hangfire for scheduled and async background jobs. The Hangfire Dashboard is available on each deployed environment at /hangfire-login (requires the Hangfire Entra role). See Hangfire Job Management for details.

Working with database migrations​

We use Entity Framework Core to generate SQL migrations and keep the database schema in sync with the domain model. Whenever you make a change to the domain model that affects the database schema, create a migration and apply it to your local database through .\dev.ps1.

.\dev.ps1 db make-migration -Project ECC -Name AddMeterStatus
.\dev.ps1 db migrate -Project All

Use -Project ECC or -Project DMC when the command should target only one database.

Generating frontend models​

Generate the frontend API models independently with:

.\dev.ps1 generateFrontendModels

Pulling changes and updating the local solution​

The following covers the usual way to pull changes, from the same branch-version that you are already on:

  1. Pull/merge from our repository using Git.
  2. Run .\dev.ps1 setup to refresh authentication and local dependencies, apply migrations, regenerate frontend models and development data, and start the default Compose stack.
  3. Continue with the IDE Docker Compose Fast-Mode launch flow when running or debugging through Visual Studio or Rider.

Resetting the local solution​

This can be required if you change the branch version or if your local database ends in a bad state. Stop the Energy Connect containers and remove the local .\volumes directory, which contains the local database data. Then rebuild the environment with:

.\dev.ps1 setup

To reset only the generated development data without recreating the entire environment, run .\dev.ps1 db seed --category <category> --reset.

Contributing​

See Version Control & Branching Strategy for information about branching.

  1. Pull from the branch you want to change from our repository.
  2. Make your changes and commit them.
  3. Push a new branch dev/[DevOps ID]-[Short meaningful text] or bug/[DevOps ID]-[Short meaningful text] to our repository.
  4. Create a pull request from that branch to the target branch version, e.g. release/3.1. Remember to link the work item you are working on.
  5. When the pull request has been approved by a colleague and completed, it is merged into the target branch.