Search Documents
Developmentsearch-documentsSearch Documents is an Agent Skill for development published in the Azure/azure-sdk-for-net repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
E2E workflow skill for Azure.Search.Documents SDK (TypeSpec + heavy customization). Handles full release cycles and partial updates: SHA update; code generation; build; customization fixes; ServiceVersion sync; testing; API export; changelog; version; samples; formatting; release metadata. WHEN: create new package version for Azure.Search.Documents; regenerate Azure.Search.Documents; fix Azure.Search.Documents bug; release Azure.Search.Documents; update Azure.Search.Documents spec. Do not use for Azure.ResourceManager.Search or Azure.Provisioning.Search.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Azure/azure-sdk-for-net/blob/HEAD/sdk/search/Azure.Search.Documents/.github/skills/search-documents/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/search-documents, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Azure.Search.Documents — Package Skill
| Property | Value |
|---|---|
| Package | Azure.Search.Documents |
| Root | sdk/search/Azure.Search.Documents/ |
| Plane | data-plane (TypeSpec → azure-typespec-http-client-csharp-emitter) |
| Service directory | search |
| TypeSpec pin | tsp-location.yaml |
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
- 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 TypeSpecclient.tspdecorators. - Check custom partials FIRST on build errors after regen — this package has 60+
[CodeGenMember], 12[CodeGenType], and 11[CodeGenSuppress]usages. The files insrc/Options/,src/Models/,src/Indexes/Models/are the most likely breakage points. [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).- ServiceVersion has 6 sync locations — enum member,
LatestVersion,TryGetServiceVersion(),Validate(),ToVersionString(),ToServiceVersion()inSearchClientOptions.cs. Missing a switch case causes a runtimeArgumentOutOfRangeException, not a compile error. - Forgetting
Export-API.ps1 search— CI ApiCompat will fail on any public API change. - Restoring a preview-only deleted type — only restore types that existed in a previous GA release. Check via git tags.
- Changelog: "Breaking Change" for unreleased type — types introduced in the current unreleased version are not breaking changes; use "Features Added" instead.
- NEVER create, modify, or delete any
ApiCompatBaseline*.txtfile — 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. - SearchModelFactory — the hand-written
SearchModelFactoryonly needs to be modified when the build fails due to a missing factory method. - Custom deserializers silently drop new fields — Some classes, such as
FacetResult.csandSearchResults.cs, have hand-written deserialization that constructs model types directly. When the generated constructor gains new parameters, do NOT just passnull/default— you must add JSON parsing logic for the new properties. See architecture.md. SearchTestBase.LatestVersionmust matchSearchClientOptions.LatestVersion— this constant intests/Utilities/SearchTestBase.cscontrols which API version all tests run against. Forgetting to update it means tests still target the old version. See testing.md.- SearchOptions new properties must go to the correct layer —
SearchOptionshas 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. - 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 newXxxType?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 summaryfor 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 inSearchOptions. - 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.
| Step | MCP Tool / Command | Notes |
|---|---|---|
| Generate | azsdk_package_generate_code with packagePath: sdk/search/Azure.Search.Documents | Takes 2+ min. Update tsp-location.yaml commit first if SHA changed. |
| Build | azsdk_package_build_code with packagePath: sdk/search/Azure.Search.Documents | Run after any src/ change. |
| Export API | eng/scripts/Export-API.ps1 search | Produces api/Azure.Search.Documents.{net10.0,net8.0,netstandard2.0}.cs. |
| Format | dotnet format src/Azure.Search.Documents.csproj + dotnet format tests/Azure.Search.Documents.Tests.csproj | |
| Snippets | eng/scripts/Update-Snippets.ps1 search | Run after adding/renaming public types in samples. |
| Tests | dotnet test tests/ --filter "TestCategory!=Live" | Recordings via assets.json + Test Proxy. |
| Check | azsdk_package_run_check with packagePath: sdk/search/Azure.Search.Documents | |
| Changelog | azsdk_package_update_changelog_content with packagePath: sdk/search/Azure.Search.Documents | May return noop — draft manually comparing to previous release tag. |
| Version | azsdk_package_update_version with packagePath: sdk/search/Azure.Search.Documents | |
| Metadata | azsdk_package_update_metadata with packagePath: sdk/search/Azure.Search.Documents |
Build Error Triage
| Error pattern | Where to fix |
|---|---|
does not contain a definition for 'X' | Custom partial in src/ — update [CodeGenMember] or property reference. See customization.md. |
type or namespace 'X' does not exist | Restore deleted type (if GA backward compat) or remove reference. See architecture.md. |
Ambiguous reference | Add [CodeGenSuppress] on the generated member. |
| Switch expression not exhaustive | Update all 6 switch locations in SearchClientOptions.cs. See architecture.md. |
Error in src/Generated/*.cs | Fix via TypeSpec client.tsp or [CodeGenSuppress] — never edit the generated file. |
| Constructor arg count mismatch in custom deserializer | Do NOT just add null/default. Read the generated model to identify new properties, then add JSON parsing logic in the custom deserializer. See architecture.md. |
New property appears on generated SearchOptions that belongs on a sub-object | Add property to SemanticSearchOptions or VectorSearchOptions, add private [CodeGenMember] redirector in Options/SearchOptions.cs, update internal ctor, regenerate. See architecture.md. |
New XxxType? property whose doc comment shows a | separator or count- / threshold- / highlight- / maxcharlength- parameter | The bare enum hides the compound format. Add a wrapper class + raw redirector — see customization.md → Compound / magic-string properties. |
MembersMustExist (ApiCompat) | A public API from a previous GA release is missing. Add a backward-compatible overload in the custom partial class that delegates to the new signature. NEVER create/update an ApiCompat baseline file. |
Workflows
Detect Scope Automatically
When the user's request doesn't specify a scenario, classify it:
| User intent | Workflow |
|---|---|
| "Create a new package with commit SHA X for version Y" / "release new version" / "new API version" | → Full Release |
| "Update spec SHA" / "spec patch" | → Spec Update |
"Fix this bug" / "add this feature" / code change in src/ | → Code Change |
| "Add customization" / "rename type" / "suppress member" | → Customization |
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
- SHA — Update
tsp-location.yamlcommitto the new SHA. - Generate — Run
azsdk_package_generate_code. - Deleted types —
git diff --diff-filter=D --name-only HEAD -- src/Generated/. Restore only types from a previous GA release (see architecture.md). - 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. - 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 passnull/default— add actual deserialization logic for the new fields. See architecture.md. After the build passes, check for new properties on the generatedSearchOptionsthat should be routed to sub-objects — see architecture.md. - Customization audit — Verify
[CodeGenSuppress]targets still exist. Verify[CodeGenType]mappings still match generated names.Select-String -Path src/**/*.cs -Pattern "CodeGen(Suppress|Type)" -Recurse. - Export API —
eng/scripts/Export-API.ps1 search. Reviewgit diff api/for expected changes. - ApiCompat —
dotnet pack src/to verify no unintended binary-breaking changes. — see Pitfall #8. - Test version — Update
LatestVersionintests/Utilities/SearchTestBase.csto match the newServiceVersionenum member. This is the single source of truth for which API version all tests target. - Tests — Add tests for new types/properties per testing.md:
- TypeCompleteness tests auto-discover new
IJsonModel<T>types (Tiers 1+2). - New
SearchOptionsproperty → add 1 line toSearchOptionsMockTests.SearchOptionProperties(). - New client operation → write recorded test + mock test.
- New preview feature → add to
*.Preview.csand tag with// search-preview:<api-version>. - New polymorphic base type → add to
SearchTestHelpers.PolymorphicBaseTypes.
- Format —
dotnet formaton both src and tests.csprojfiles. - Snippets —
eng/scripts/Update-Snippets.ps1 search. - Run tests —
dotnet test tests/ --filter "TestCategory!=Live". - Run checks —
azsdk_package_run_check. - 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/*.csand git tags.
- Version & metadata —
azsdk_package_update_version,azsdk_package_update_metadata. - Prepare release —
./eng/common/scripts/Prepare-Release.ps1 Azure.Search.Documents. - Final gate — Re-run Export-API if
src/changed since step 7. Re-run snippets if*.mdchanged since step 12. Confirmgit statusshows only expected changes.
Spec Update (same API version, unreleased)
- Update
tsp-location.yamlcommit. - Run
azsdk_package_generate_code. - Run
azsdk_package_build_codeand fix errors. - Check deleted types (restore only GA types).
- Update handwritten code as needed.
- → Continue from Finalize step 7.
Code Change (bug fix, feature addition)
- Make the code change in custom files under
src/(neversrc/Generated/). - Regenerate the code in case there are generation changes.
- Run
azsdk_package_build_code. - Add/update tests for the change.
- → Continue from Finalize step 7.
Customization (add/update CodeGen attributes)
- Identify the generated type in
src/Generated/(do not edit it). - Create or update the custom partial in
src/. See customization.md for attribute patterns. - Prefer TypeSpec
client.tspfor cross-language concerns (@@clientName,@@access). Use C# customization only for language-specific behavior. - Regenerate the code to verify the change is applied correctly.
- Run
azsdk_package_build_codeand fix any errors. - → Continue from Finalize step 7.
Finalize
All workflows converge here. Skip steps that don't apply.
- Export API —
eng/scripts/Export-API.ps1 search(if public API changed). - Format —
dotnet formaton src and tests. - Snippets —
eng/scripts/Update-Snippets.ps1 search(if public types changed in samples). - Tests —
dotnet test tests/ --filter "TestCategory!=Live". - Checks —
azsdk_package_run_check. - Changelog — Update
CHANGELOG.md(patch in-place if unreleased; cross-check againstapi/*.cs). - Version & metadata — Update if this is a versioned release.
- Final gate —
git diffto review all changes. Ensure no untracked generated files.