|
| 1 | +# AGENTS.md — FSharp.Data.SqlClient |
| 2 | + |
| 3 | +Developer and AI-agent quick-reference for building, testing, and CI checks. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +- **.NET 9 SDK** — required; pinned in `global.json` |
| 8 | +- **A SQL Server instance** with the [AdventureWorks2012](https://github.com/Microsoft/sql-server-samples) database attached (used by all runtime tests) |
| 9 | +- Local tools are declared in `.config/dotnet-tools.json`; restore once per clone: |
| 10 | + |
| 11 | +``` |
| 12 | +dotnet tool restore |
| 13 | +``` |
| 14 | + |
| 15 | +This installs **Paket 10** and **Fantomas 7**. |
| 16 | + |
| 17 | +## Restoring packages |
| 18 | + |
| 19 | +Paket manages all NuGet dependencies. After `dotnet tool restore`, run: |
| 20 | + |
| 21 | +``` |
| 22 | +dotnet paket install # re-resolves + updates paket.lock (after editing paket.dependencies) |
| 23 | +dotnet paket restore # fast restore from existing paket.lock (normal dev workflow) |
| 24 | +``` |
| 25 | + |
| 26 | +The paket.lock is committed and should be kept up-to-date. Do not edit `packages/` by hand. |
| 27 | + |
| 28 | +## Building |
| 29 | + |
| 30 | +``` |
| 31 | +# Build the main library + design-time assembly |
| 32 | +dotnet build SqlClient.sln -c Release |
| 33 | +
|
| 34 | +# Build the console sample (requires the library to be built first) |
| 35 | +dotnet build Samples.sln -c Release |
| 36 | +
|
| 37 | +# Build the test projects |
| 38 | +dotnet build Tests.sln -c Release |
| 39 | +``` |
| 40 | + |
| 41 | +The FAKE-based build script in `build/` orchestrates everything in order: |
| 42 | + |
| 43 | +``` |
| 44 | +cd build |
| 45 | +dotnet run # runs all: Clean → CheckFormat → AssemblyInfo → Build → … |
| 46 | +dotnet run -- Build # run a single target |
| 47 | +``` |
| 48 | + |
| 49 | +## Code formatting (Fantomas) |
| 50 | + |
| 51 | +All F# source in `src/`, `tests/`, and `build/` is formatted with Fantomas. |
| 52 | + |
| 53 | +``` |
| 54 | +# Format in-place |
| 55 | +dotnet fantomas src tests build |
| 56 | +
|
| 57 | +# Check only (what CI does — fails if any file needs reformatting) |
| 58 | +dotnet fantomas src tests build --check |
| 59 | +``` |
| 60 | + |
| 61 | +CI will fail if any file is not formatted. **Always run the formatter before committing.** |
| 62 | + |
| 63 | +Formatting configuration is in [.fantomasrc](.fantomasrc); editor settings in [.editorconfig](.editorconfig). |
| 64 | + |
| 65 | +## Running tests |
| 66 | + |
| 67 | +Tests require a live SQL Server with AdventureWorks2012. The connection string is read from `tests/SqlClient.Tests/app.config` (key `AdventureWorks`) or the environment variable `GITHUB_ACTION_SQL_SERVER_CONNECTION_STRING`. |
| 68 | + |
| 69 | +``` |
| 70 | +dotnet test tests/SqlClient.Tests/SqlClient.Tests.fsproj -f net9.0 |
| 71 | +dotnet test tests/SqlClient.DesignTime.Tests/SqlClient.DesignTime.Tests.fsproj -f net9.0 |
| 72 | +``` |
| 73 | + |
| 74 | +## CI readiness checklist |
| 75 | + |
| 76 | +Before opening a PR, ensure: |
| 77 | + |
| 78 | +1. `dotnet paket restore` succeeds (paket.lock is committed and up-to-date). |
| 79 | +2. `dotnet build SqlClient.sln -c Release` — no errors (FS0044 deprecation warnings for `System.Data.SqlClient` are expected and suppressed). |
| 80 | +3. `dotnet fantomas src tests build --recurse --check` — exits 0 (no unformatted files). |
| 81 | +4. Tests pass against a SQL Server instance with AdventureWorks2012. |
| 82 | + |
| 83 | +## Repository layout |
| 84 | + |
| 85 | +| Path | Purpose | |
| 86 | +|---|---| |
| 87 | +| `src/SqlClient/` | Runtime library (`FSharp.Data.SqlClient.dll`), targets `netstandard2.0;net9.0` | |
| 88 | +| `src/SqlClient.DesignTime/` | Design-time assembly, targets `net9.0` | |
| 89 | +| `src/SqlClient.Samples/ConsoleSample/` | Runnable demo of `SqlCommandProvider`, `SqlProgrammabilityProvider`, `SqlEnumProvider` | |
| 90 | +| `src/SqlClient.TestProjects/` | Integration test helpers (Lib, NetCoreApp) | |
| 91 | +| `tests/SqlClient.Tests/` | Main test suite, `net9.0` | |
| 92 | +| `tests/SqlClient.DesignTime.Tests/` | Design-time-specific tests, `net9.0` | |
| 93 | +| `build/` | FAKE + Fun.Build pipeline (`dotnet run`) | |
| 94 | +| `paket.dependencies` | Top-level package declarations (no .NET Framework groups) | |
| 95 | +| `.config/dotnet-tools.json` | Local tool manifest (paket, fantomas) | |
| 96 | + |
| 97 | +## Notes for agents |
| 98 | + |
| 99 | +- **No .NET Framework / Mono support.** All target frameworks are `net9.0` or `netstandard2.0`. Do not add `net462`, `net471`, or similar TFMs. |
| 100 | +- **Paket manages packages.** Do not use `dotnet add package`. Edit `paket.dependencies` and run `dotnet paket install` instead. |
| 101 | +- `System.Data.SqlClient` (legacy) is used intentionally. Migration to `Microsoft.Data.SqlClient` is a future task; FS0044 warnings are suppressed. |
| 102 | +- The design-time assembly output path is `bin/typeproviders/fsharp41/net9.0/` — this is the standard layout expected by the F# type-provider SDK. |
0 commit comments