Skip to content

Building and development

Sending a pull request? CONTRIBUTING.md says what it needs.

Build from source

Install the .NET 10 SDK named in global.json, that exact version (dotnet --list-sdks shows what you have), then publish:

dotnet publish .\src\HASS.Agent.NET10\HASS.Agent.NET10.csproj `
    -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true

The output goes to:

src\HASS.Agent.NET10\bin\Release\net10.0-windows10.0.19041.0\win-x64\publish\HASS.Agent.NET10.exe

The publish is self-contained: the .NET runtime of that SDK goes into the exe, and Windows Update does not patch it there. That is why global.json pins the SDK: the release is built on a known runtime, CI uses the same one, and Dependabot opens a pull request for each new .NET 10 SDK (a new major version is left out: moving to it is a change of its own). When a new SDK brings .NET security fixes, merging it is the cue for a release built on it, whose notes name the CVEs; nothing does that by itself. See Security and privacy.

To build the installer, also install Inno Setup and compile installer\HASS.Agent.NET10.iss.

build-exe.ps1 wraps the common cases: on its own it produces a standalone .exe and offers to swap it into the installed copy; -Tag builds the signed installer and zip with the CI file names (see Security and privacy; it needs the maintainer's certificate, so this is a release tool rather than a build step).

Tests

tests/HASS.Agent.NET10.Tests holds the unit tests (xUnit v3). They cover the logic that has an input and an output: version comparison and the choice of release asset, the release notes shown in the update prompt, notification payloads (buttons, text fields, durations), key combinations and hotkeys, popup window sizes, LibreHardwareMonitor readings, sensor profiles and the publish pace, settings normalization, the local API key check and the signature check of update installers. What needs Windows itself (displays, audio devices, the tray icon, the windows) is tested by hand on real PCs.

dotnet test --project tests/HASS.Agent.NET10.Tests -c Release

global.json selects the Microsoft.Testing.Platform runner that xUnit v3 uses. The installer signature tests need a signed release installer, which is too big for the repository. CI downloads the installer of the latest release; locally, set HASS_AGENT_SIGNED_INSTALLER to one (for example artifacts\installer\HASS.Agent.NET10-Setup-<version>.exe after build-exe.ps1 -Tag), otherwise those tests are skipped. The audio tests run on the PC's own default output device and are skipped where there is none; they play silence and read, and the one that turns the mute over for a moment to see the notification runs only with HASS_AGENT_AUDIO_TESTS=1. The popup window tests that put small empty windows on the screen for a few seconds run only with HASS_AGENT_WINDOW_TESTS=1.

Every bug fix comes with a test that fails without the fix, so the same bug cannot come back unnoticed.

GitHub Actions

The repository's Windows workflow:

  • the unit tests (a release build waits for them)
  • dotnet restore + dotnet build -c Release
  • self-contained win-x64 publish
  • Inno Setup installer build
  • downloadable artifacts from manual workflow runs: HASS.Agent.NET10-win-x64 and HASS.Agent.NET10-Setup
  • release assets on v* tags, attached to a draft release (the signed files replace them before it is published): HASS.Agent.NET10-Setup-<version>.exe and HASS.Agent.NET10-win-x64-<version>.zip

Everything up to the installer runs with a read-only token, for pull requests too. Only a last job, which runs for a pushed tag alone and builds nothing, may write to the repository: it makes the draft release from the files the build handed over, and leaves a release that is already published as it is.

Packages

The NuGet packages come from nuget.org only (NuGet.config), and the ones a build takes are written down, each with its hash, in packages.lock.json next to the two projects. CI and a release build restore in locked mode: if the lock files do not match what the projects ask for, the restore fails (NU1004) instead of taking something else. After changing a package, or the SDK version in global.json (one package comes with the SDK), write them again and commit them:

dotnet restore src/HASS.Agent.sln --force-evaluate

Beside it: CodeQL on every change, the OpenSSF Scorecard, the Sigstore signing of a published release, and the website build below.

Minimal development setup

You do not need Visual Studio for this project.

Required:

  • .NET 10 SDK for Windows x64
  • PowerShell

Optional:

  • Visual Studio Code
  • C# Dev Kit extension

Useful commands:

dotnet nuget list source
dotnet --list-sdks
dotnet build .\src\HASS.Agent.NET10\HASS.Agent.NET10.csproj -c Release
dotnet run --project .\src\HASS.Agent.NET10\HASS.Agent.NET10.csproj -c Release

If dotnet nuget list source says No sources found, add the official NuGet feed:

dotnet nuget add source https://api.nuget.org/v3/index.json --name nuget.org

The technical developer notes: src/HASS.Agent.NET10/README.md.

The website

This site is built by MkDocs with the Material theme from the markdown files under docs/; mkdocs.yml holds the navigation, website/hooks.py pulls in the changelog and the integration's README. A push to main that touches them deploys it through GitHub Pages. To see it on your PC:

python -m venv .venv
.venv\Scripts\pip install -r website\requirements.txt
.venv\Scripts\mkdocs serve

A new feature gets a page, or a section of one, under docs/, and one line in the README's feature table.