CONFIG: Fix net10.0 targets paths, add LibPostalAutoDownload opt-out, document usage

[perirrs]

Fixes AB#29898

Also addresses #97 and #52.

1. Release blocker — native files not found (no issue, found while reviewing #97)

b3442e9 moved the packed natives from contentFiles/any/net8.0/ to contentFiles/any/net10.0/, but NHSISL.LibPostalClient.targets still resolved them from the net8.0 paths. The targets file was never updated.

Verified against a real consumer project referencing the packed package:

Package	Consumer build	Natives in output
current main	fails MSB3030	none
this branch	succeeds	libpostal-1.dll, libpostal.h

The unfixed error:

error MSB3030: Could not copy the file
"...\build\..\contentFiles\any\net8.0\libpostal.h" because it was not found.

This is a hard build failure for every consumer, not a runtime error. It would have shipped in v1.0.1.0.

2. LibPostalAutoDownload opt-out (#97)

Adds an MSBuild property, default true so existing behaviour is unchanged:

<PropertyGroup>
  <LibPostalAutoDownload>false</LibPostalAutoDownload>
</PropertyGroup>

When false: the download is skipped on both build and publish, and Clean no longer deletes LibpostalData.zip — which was what caused the next build to re-download it.

Note the publish path (PrepLibPostalPublish) downloaded unconditionally on every publish, so that is now gated and existence-checked too.

Verified:

Scenario	Result
LibPostalAutoDownload=false	no download
default, zip absent	downloads and unzips
default, zip present	skips download
Clean with opt-out	zip preserved
Clean default	zip deleted
consumer project with opt-out	builds, natives copied, no download

3. README usage docs (#52)

Open since September 2024, asking how to actually use the package — the README had no usage section. Adds install, parse and expand examples, a config table, the new opt-out, and a note on the #58 test-project DllNotFoundException with its workaround.

All samples and their outputs were run against the package built from this branch, so the parser labels are real output.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR fixes NuGet package build/publish behavior by correcting the packaged native/content file paths for net10.0, adding an MSBuild opt-out for automatic libpostal data download, and documenting end-to-end usage in the README so consumers can successfully install and use the library.

Changes:

• Update NHSISL.LibPostalClient.targets to resolve native/header assets from contentFiles/any/net10.0/ (instead of net8.0/).
• Add LibPostalAutoDownload (default true) to gate data download on both build and publish, and prevent Clean from deleting LibpostalData.zip when opted out.
• Expand README.md with install, parse/expand examples, configuration guidance, and test-project usage notes.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
README.md	Adds usage documentation, examples, configuration table, and guidance for controlling downloads and test-project usage.
NHSISL.LibPostalClient/NHSISL.LibPostalClient.targets	Fixes content file paths to net10.0 and introduces LibPostalAutoDownload gating for download/clean/publish behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.