Send a random per-installation ID as the tag "install" (0.3.0)

[dmccoystephenson]

Summary

trace-client-java 0.5.0's per-installation ID is ported to the C# client, so the trace server can count distinct installations rather than raw events. Version bumped 0.2.0 → 0.3.0 (csproj, file header, TraceClient.Version).

• Tag install on every event when the program supplies an ID. It is added after version; an event's own install tag wins; it is never added past the 32-tag limit (counted the way Json counts, so the event is not dropped for it).
• Constructor options (new optional named parameters at the end, so existing calls are unchanged):
  • installId: — explicit ID, trimmed; null/blank = none; over 255 characters throws ArgumentException (param installId), exactly like an overlong version.
  • installIdFile: — a path the program chooses. Used only when installId is not given.
• Resolved only after every opt-out (TRACE_USAGE_REPORTING / DO_NOT_TRACK, enabled: false, no key): a disabled client never generates or writes an ID.
• TraceClient.InstallId — the ID in use; null when disabled or none.
• TraceClient.InstallIdFromFile(string path) — static helper: returns the first line matching ^[A-Za-z0-9_.-]{1,255}$; when the file is missing or has no such line, writes a new Guid (creating parent directories). A file that exists but cannot be read is not overwritten; any read/write failure, or a blank path, yields an in-memory ID. Never throws. There is no default location. Calling it directly writes whatever the opt-outs say; that is documented, and installIdFile: is recommended instead.
• README: new section "Every event carries a random installation ID" (what is sent, where it lives, how to reset, opt-outs stop it, explicit-ID example); wire-format example and User-Agent version updated.

Tests

New tests/TraceClient.Tests/InstallIdTest.cs (13 tests) mirrors the Java suite: persist once + reuse, first valid line read / junk file replaced, unwritable path (parent is a regular file) → in-memory without throwing, unreadable path not overwritten, client persists and sends the ID on every event, unwritable file still reports, disabled (config / no key / DO_NOT_TRACK / TRACE_USAGE_REPORTING) → nothing written and no ID, explicit ID trimmed and wins over the file, blank = no tag, overlong rejected, event install override, tag cap.

dotnet test -c Release -p:IncludeNetFramework=false (the CI command, net8.0) was run locally: 64 passed, 0 failed. The net48 leg runs only on CI (Windows).

Not merged, tagged or released; no consumer repos touched.

🤖 Generated with Claude Code

https://claude.ai/code/session_014ztkfamsbEqQfcu76me5SL

---

drafted by Claude on behalf of Daniel Stephenson