# Dependency notes for .NET

A `PackageReference` records a package ID and a version. It does not say why the package is there, which framework upgrade it is waiting for, or which packages have to move with it. An XML comment has room for a phrase, and it stays in the one project file that has it.

Pacmon keeps a note for each package in `.pacmon/nuget/DEPENDENCY-NOTES.md` and shows it on the package's line. C#, F# and Visual Basic projects are read alike, and under central package management the versions in `Directory.Packages.props` are read too, keyed by the same package ID.

## What Pacmon reads

- **Manifest:** `*.csproj`, `*.fsproj`, `*.vbproj`, `Directory.Packages.props`
- **Notes file:** `.pacmon/nuget/DEPENDENCY-NOTES.md`
- **Section heading:** the case-insensitive package ID as written: `## Newtonsoft.Json`

Pacmon reads literal `PackageReference Include` items in C#, F# and VB project files; and `PackageVersion Include/Update` plus `GlobalPackageReference Include` items in `Directory.Packages.props`. Package IDs are matched case-insensitively. Imports, MSBuild expressions, project/framework references, downloads and transitive packages are not evaluated.

Pacmon never runs .NET, MSBuild or NuGet, so it needs no SDK and restores nothing.

## Example

```xml
<ItemGroup>
  <PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.11" />
  <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="8.0.11" />
  <PackageReference Include="Serilog.AspNetCore" Version="8.0.3" />
</ItemGroup>
```

`.pacmon/nuget/DEPENDENCY-NOTES.md`:

```md
## Microsoft.EntityFrameworkCore

Stay on 8 until the API moves to .NET 9 (PLAT-212).

### Agent notes

- purpose: ORM for the orders database
- constraint: keep the major equal to the target framework (net8.0)
- bump-with: Npgsql.EntityFrameworkCore.PostgreSQL
- verify: `dotnet test` and `dotnet ef database update` on an empty database
- verified: 8.0.11
```

The heading is the package ID as the project file writes it; IDs are matched without regard to case.

## Editors

The notes file is the same in all three, so one team can mix them: **Visual Studio** 2022 and newer on Windows, **Rider** and other JetBrains IDEs, and **VS Code**. In Visual Studio the note shows in Quick Info on the package ID, the Pacmon mark beside it opens the note, and **Tools → Options → Pacmon** holds the settings.

## For AI coding agents

An agent reads a package's section before it adds, upgrades or removes the package. `bump-with:` lists the packages that have to move with it, and `verify:` the tests to run afterwards. See [the rules agents follow](https://pacmon.dev/agents/).