search-documents

Azure.Search.Documents — Package Skill

References (load on demand):

• references/architecture.md — source layout, generated-vs-custom map, service version management, SearchOptions three-layer architecture, backward compat rules
• references/customization.md — CodeGen attributes, TypeSpec-vs-C# decision table, per-type map, SearchOptions redirector patterns, post-regen update guide
• references/testing.md — coverage tiers, version matrix, preview isolation, post-regen test workflow

Related skills:

• search-documents-typespec-validation — exhaustive SDK ↔ TypeSpec parity check at a single commit
• search-documents-version-diff — diff public API surface between two versions to catch regressions

---

Common Pitfalls

1. Never hand-edit src/Generated/ — files with // <auto-generated/> header are overwritten on regeneration. All modifications go through custom partial classes, [CodeGenSuppress]/[CodeGenType]/[CodeGenMember] attributes, or TypeSpec client.tsp decorators.
2. Check custom partials FIRST on build errors after regen — this package has 60+ [CodeGenMember], 12 [CodeGenType], and 11 [CodeGenSuppress] usages. The files in src/Options/, src/Models/, src/Indexes/Models/ are the most likely breakage points.
3. [CodeGenSuppress] fails silently — if the generator renames/removes a member, a stale [CodeGenSuppress] does nothing (no compile error, but the generated member reappears in the public API).
4. ServiceVersion has 6 sync locations — enum member, LatestVersion, TryGetServiceVersion(), Validate(), ToVersionString(), ToServiceVersion() in SearchClientOptions.cs. Missing a switch case causes a runtime ArgumentOutOfRangeException, not a compile error.
5. Forgetting Export-API.ps1 search — CI ApiCompat will fail on any public API change.
6. Restoring a preview-only deleted type — only restore types that existed in a previous GA release. Check via git tags.
7. Changelog: "Breaking Change" for unreleased type — types introduced in the current unreleased version are not breaking changes; use "Features Added" instead.
8. NEVER create, modify, or delete any ApiCompatBaseline*.txt file — ApiCompat failures mean a public API from a previous GA release is missing. The fix is ALWAYS to add a backward-compatible overload in custom code (e.g., [EditorBrowsable(Never)] shim that delegates to the new signature). Creating a baseline file suppresses the error without fixing the break, which ships a broken package. If you cannot find a way to add a compatible overload, stop and ask the user.
9. SearchModelFactory — the hand-written SearchModelFactory only needs to be modified when the build fails due to a missing factory method.
10. Custom deserializers silently drop new fields — Some classes, such as FacetResult.cs and SearchResults.cs, have hand-written deserialization that constructs model types directly. When the generated constructor gains new parameters, do NOT just pass null/default — you must add JSON parsing logic for the new properties. See architecture.md.
11. SearchTestBase.LatestVersion must match SearchClientOptions.LatestVersion — this constant in tests/Utilities/SearchTestBase.cs controls which API version all tests run against. Forgetting to update it means tests still target the old version. See testing.md.
12. SearchOptions new properties must go to the correct layer — SearchOptions has a three-layer architecture: public sub-objects (SemanticSearchOptions, VectorSearchOptions), private [CodeGenMember] redirectors, and the flat generated model. A new generated property must be routed to the correct sub-object (or left as a direct property) and the internal constructor must be updated. Leaving a new property on the generated auto-property creates a discrepancy between the public API and the wire format. See architecture.md for the decision tree and checklists.
13. Compound / magic-string properties are silently broken when exposed as the bare enum — properties typed as XxxType? whose service format is a pipe-delimited compound string (e.g. extractive|count-5,threshold-0.9, generative|count-3) lose the parameter portion if the SDK exposes just the enum. After any regen, scan new XxxType? properties for compound formats in their doc comments and wrap them following customization.md → Compound / magic-string properties. Existing reference implementations: QueryAnswer, QueryCaption, QueryRewrites.

---

Preview Feature Markers

Preview-only code is tagged with // search-preview:<api-version> comments (NOT #if preprocessor directives — those break code generation).

Two forms:

// Single-line — marks the next statement or declaration
public HybridSearch HybridSearch { get; set; } // search-preview:2026-05-01-preview

// Block — wraps multiple related declarations or statements
// search-preview:2026-05-01-preview {
public QueryLanguage? QueryLanguage { get; set; }
public QueryRewrites QueryRewrites { get; set; }
// search-preview:2026-05-01-preview }

Detection script: .github/skills/search-documents/scripts/Find-PreviewFeatures.ps1

• -Format summary for human-readable output
• -Format json (default) for agent consumption
• -ApiVersion "2026-05-01-preview" to filter

Key rules:

• [CodeGenMember] redirectors must NEVER be inside preview markers — the generator must always see them regardless of version.
• Preview markers go on the public-facing property (on SemanticSearchOptions, VectorSearchOptions, etc.), not on the private serialization redirector in SearchOptions.
• For GA release: remove or comment out all code inside markers for the graduating version.
• For new preview features: use the new version string (e.g. // search-preview:2027-01-01-preview).

---

Tools

ALWAYS use MCP tools when available. Fall back to manual scripts only when a tool is unavailable or fails.

Build Error Triage

---

Workflows

Detect Scope Automatically

When the user's request doesn't specify a scenario, classify it:

All workflows converge on the same finalization steps. Skip steps that don't apply (e.g., no ServiceVersion update for a bug fix that doesn't change the API version).

---

Full Release (new API version or new package version)

Input: spec commit SHA, target version string, GA or preview

1. SHA — Update tsp-location.yaml commit to the new SHA.
2. Generate — Run azsdk_package_generate_code.
3. Deleted types — git diff --diff-filter=D --name-only HEAD -- src/Generated/. Restore only types from a previous GA release (see architecture.md).
4. ServiceVersion — In SearchClientOptions.cs, add new enum member and update all 6 locations. For GA: remove preview versions. For preview: keep only latest preview. See architecture.md.
5. Build & fix — Run azsdk_package_build_code. Fix errors using the build error triage table and customization.md. CRITICAL: When fixing constructor arg mismatches in custom deserializers (FacetResult.cs, SearchResults.cs), do NOT pass null/default — add actual deserialization logic for the new fields. See architecture.md. After the build passes, check for new properties on the generated SearchOptions that should be routed to sub-objects — see architecture.md.
6. Customization audit — Verify [CodeGenSuppress] targets still exist. Verify [CodeGenType] mappings still match generated names. Select-String -Path src/**/*.cs -Pattern "CodeGen(Suppress|Type)" -Recurse.
7. Export API — eng/scripts/Export-API.ps1 search. Review git diff api/ for expected changes.
8. ApiCompat — dotnet pack src/ to verify no unintended binary-breaking changes. — see Pitfall #8.
9. Test version — Update LatestVersion in tests/Utilities/SearchTestBase.cs to match the new ServiceVersion enum member. This is the single source of truth for which API version all tests target.
10. Tests — Add tests for new types/properties per testing.md:

• TypeCompleteness tests auto-discover new IJsonModel<T> types (Tiers 1+2).
• New SearchOptions property → add 1 line to SearchOptionsMockTests.SearchOptionProperties().
• New client operation → write recorded test + mock test.
• New preview feature → add to *.Preview.cs and tag with // search-preview:<api-version>.
• New polymorphic base type → add to SearchTestHelpers.PolymorphicBaseTypes.

11. Format — dotnet format on both src and tests .csproj files.
12. Snippets — eng/scripts/Update-Snippets.ps1 search.
13. Run tests — dotnet test tests/ --filter "TestCategory!=Live".
14. Run checks — azsdk_package_run_check.
15. Changelog — Update CHANGELOG.md:
    • If topmost version is unreleased, patch in-place. Only create a new section when topmost has shipped.
    • Breaking changes = only removals/renames from a previously released version. Cross-check against api/*.cs and git tags.
16. Version & metadata — azsdk_package_update_version, azsdk_package_update_metadata.
17. Prepare release — ./eng/common/scripts/Prepare-Release.ps1 Azure.Search.Documents.
18. Final gate — Re-run Export-API if src/ changed since step 7. Re-run snippets if *.md changed since step 12. Confirm git status shows only expected changes.

---

Spec Update (same API version, unreleased)

1. Update tsp-location.yaml commit.
2. Run azsdk_package_generate_code.
3. Run azsdk_package_build_code and fix errors.
4. Check deleted types (restore only GA types).
5. Update handwritten code as needed.
6. → Continue from Finalize step 7.

---

Code Change (bug fix, feature addition)

1. Make the code change in custom files under src/ (never src/Generated/).
2. Regenerate the code in case there are generation changes.
3. Run azsdk_package_build_code.
4. Add/update tests for the change.
5. → Continue from Finalize step 7.

---

Customization (add/update CodeGen attributes)

1. Identify the generated type in src/Generated/ (do not edit it).
2. Create or update the custom partial in src/. See customization.md for attribute patterns.
3. Prefer TypeSpec client.tsp for cross-language concerns (@@clientName, @@access). Use C# customization only for language-specific behavior.
4. Regenerate the code to verify the change is applied correctly.
5. Run azsdk_package_build_code and fix any errors.
6. → Continue from Finalize step 7.

---

Finalize

All workflows converge here. Skip steps that don't apply.

7. Export API — eng/scripts/Export-API.ps1 search (if public API changed).
8. Format — dotnet format on src and tests.
9. Snippets — eng/scripts/Update-Snippets.ps1 search (if public types changed in samples).
10. Tests — dotnet test tests/ --filter "TestCategory!=Live".
11. Checks — azsdk_package_run_check.
12. Changelog — Update CHANGELOG.md (patch in-place if unreleased; cross-check against api/*.cs).
13. Version & metadata — Update if this is a versioned release.
14. Final gate — git diff to review all changes. Ensure no untracked generated files.