NuGet Preview Bootstrap (Offline-Friendly)
Audience: developers and Offline Kit operators restoring the Stella Ops .NET build. Purpose: Mirror the .NET preview packages the build depends on into a local, air-gap-friendly feed so
dotnet restorenever needs to reach the public internet.
The Stella Ops build relies on .NET 10 RC2 packages (Microsoft.Extensions.*, JwtBearer 10.0 RC). The repo-root NuGet.config wires three sources, in priority order:
local→./local-nuget(preferred, air-gapped mirror)dotnet-public→https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public/nuget/v3/index.jsonnuget.org→ fallback for everything else
Follow the steps below whenever you refresh the repo or roll a new Offline Kit drop.
1. Mirror the preview packages
./ops/devops/sync-preview-nuget.sh
- Reads
ops/devops/nuget-preview-packages.csv. Each line specifies the package, version, expected SHA-256 hash, and (optionally) the flat-container base URL (we pin todotnet-public). - Downloads the
.nupkgstraight into./local-nuget/and re-verifies the checksum. Existing files are skipped when hashes already match. - Use
NUGET_V2_BASEif you need to temporarily point at a different mirror.
Tip: The script never mutates packages in place — if a checksum changes you will see a
SHA mismatch ... refreshingmessage.
2. Restore using the shared NuGet.config
From the repo root:
DOTNET_NOLOGO=1 dotnet restore src/Excititor/__Libraries/StellaOps.Excititor.Connectors.Abstractions/StellaOps.Excititor.Connectors.Abstractions.csproj \
--configfile NuGet.config
The packageSourceMapping section keeps Microsoft.Extensions.*, Microsoft.AspNetCore.*, and Microsoft.Data.Sqlite bound to local/dotnet-public, so dotnet restore never has to reach out to nuget.org when mirrors are populated.
Before committing changes (or when wiring up a new environment) run:
python3 ops/devops/validate_restore_sources.py
The validator asserts:
NuGet.configlistslocal→dotnet-public→nuget.orgin that order.Directory.Build.propspinsRestoreSourcesso every project prioritises the local mirror.- No stray
NuGet.configfiles shadow the repo root configuration.
CI executes the validator in both the build-test-deploy and release workflows, so regressions trip before any restore/build begins.
If you run fully air-gapped, remember to clear the cache between SDK upgrades:
dotnet nuget locals all --clear
3. Troubleshooting
| Symptom | Fix |
|---|---|
dotnet restore still hits nuget.org for preview packages | Re-run sync-preview-nuget.sh to ensure the .nupkg exists locally, then delete ~/.nuget/packages/microsoft.extensions.* so the resolver picks up the mirrored copy. |
| SHA mismatch in the manifest | Update ops/devops/nuget-preview-packages.csv with the new version + checksum (from the feed) and re-run the sync script. |
| Azure DevOps feed throttling | Set DOTNET_PUBLIC_FLAT_BASE env var and point it at your own mirrored flat-container, then add the URL to the 4th column of the manifest. |
Keep this doc alongside Offline Kit instructions so air-gapped operators know exactly how to refresh the mirror and verify packages before restore.