Contributor setup
This guide is for developers working on the SDK repository, not for consumers installing the NuGet package. For package usage, start with Getting started.
Prerequisites
Install both .NET SDKs:
| SDK | Why |
|---|---|
| .NET 10.0 | Primary focus; required for the Blazor sample app |
| .NET 8.0 | SDK package multi-targets net8.0 |
CI installs both 8.0.x and 10.0.x (see .github/workflows/ci.yml).
Verify installation
dotnet --list-sdks
You should see 8.x and 10.x entries. global.json pins SDK 10.0.300 with rollForward: latestFeature for the build orchestrator.
WSL / Ubuntu
Install from Microsoft’s .NET install instructions or use dotnet-install.sh. Avoid relying on the distro dotnet metapackage alone - it may not include the versions this repository targets.
Common build failure
If dotnet build fails with an error about a missing .NET 8.0 targeting pack or SDK, install the .NET 8 SDK. The solution builds net8.0 and net10.0 projects even when your default SDK is 10.x.
Clone and build
git clone https://github.com/markheydon/freeagent-dotnet.git
cd freeagent-dotnet
dotnet clean FreeAgent.slnx
dotnet restore FreeAgent.slnx
dotnet build FreeAgent.slnx --no-restore --configuration Release -warnaserror
dotnet test FreeAgent.slnx --no-build --configuration Release
Or as a single chain:
dotnet clean FreeAgent.slnx && \
dotnet restore FreeAgent.slnx && \
dotnet build FreeAgent.slnx --no-restore --configuration Release -warnaserror && \
dotnet test FreeAgent.slnx --no-build --configuration Release
Warnings fail the build (TreatWarningsAsErrors in Directory.Build.props; -warnaserror on the CLI matches that when you invoke dotnet build directly).
Use dotnet test -f net10.0 or dotnet test -f net8.0 to test a single target framework.
Verify formatting
CI runs dotnet format with --verify-no-changes. Check locally before pushing:
dotnet format FreeAgent.slnx --verify-no-changes
If changes are reported, run dotnet format FreeAgent.slnx and commit the result.
Sample app
The Blazor sample requires .NET 10 and FreeAgent OAuth credentials. See samples/README.md.
CI sandbox smoke
To enable live API smoke on main, configure GitHub Actions secrets using CI sandbox smoke. The smoke suite performs live writes in sandbox via --run-all.
When adding or retrofitting SDK endpoints, build sample probe pages per Sample probe pages. Use Company and Contacts as references.
Documentation site
Consumer docs live in docs/ and publish to GitHub Pages. Preview locally with Docker or Podman (no Ruby install):
./scripts/invoke-docs-site.sh serve
./scripts/invoke-docs-site.sh preview
See docs/README.md for details. When adding SDK reference pages, follow the existing pages under docs/reference/.
Before contributing
Read CONTRIBUTING.md, CONVENTIONS.md, and AGENTS.md.