azure-search-documents

name

azure-search-documents

description

Post-regeneration customization guide for azure-search-documents SDK. Covers error diagnosis, customization patterns, and search-specific fixes after tsp-client update. WHEN: regenerate azure-search-documents; fix azure-search-documents build errors; azure-search-documents customization errors; azure-search-documents API version update; update azure-search-documents service version. Use when this capability is needed.

azure-search-documents -- Package Skill

The generate-sdk-locally shared skill handles generation, build, test, and customization workflows -- including running azsdk_customized_code_update when builds fail. This skill activates after those tools have been tried. It covers what they can't solve: search-specific error diagnosis, customization fragility patterns, and convenience layer design.

Common Pitfalls

• Never hand-edit generated files. Files with // Code generated by Microsoft (R) TypeSpec Code Generator. are overwritten on every tsp-client update. All modifications go through SearchCustomizations.java.
• Check SearchCustomizations.java FIRST when generated files have errors. The customizations run during generation and can produce broken output if the generated code structure changed. The most common culprits:
  • hideWithResponseBinaryDataApis() -- rewires method bodies across packages, can create cross-package import mismatches
  • includeOldApiVersions() -- can duplicate enum constants the generator now produces
  • addSearchAudienceScopeHandling() -- may fail if builder structure changed
• Methods without @Generated in generated files are hand-written. These are convenience wrappers that the generator preserves but does NOT update. After regeneration, you must manually update them to match any changed generated signatures. Look at how the @Generated methods in the same file were updated as a pattern to follow.
• includeOldApiVersions can create duplicate enum constants. If the generator starts producing a version that was previously only in the customization list, you get a compilation error. Remove the version from the customization list.

After Regeneration -- Diagnose and Fix Build Errors

Categorize each compilation error:

Error location	What it means	Where to fix
Generated file, @Generated method	Customization produced broken output	Fix SearchCustomizations.java -- update AST queries to match new generated code
Generated file, method WITHOUT @Generated	Hand-written wrapper references changed generated types	Fix the hand-written method -- match the pattern used by @Generated methods in the same file
Hand-written file (SearchUtils.java, FieldBuilder.java, batching, tests)	References removed/renamed generated types	Fix the hand-written file

Verify Service Version

SearchServiceVersion.java is generated but customized by SearchCustomizations.java.

1. Check getLatest() returns the new version
2. In includeOldApiVersions():
   • Remove any version the generator now produces (prevents duplicates)
   • Add the previous latest version if not already produced by the generator
3. Verify all expected old versions are present

Detect Breaking Changes

# Removed/renamed public types
git diff --name-status HEAD -- sdk/search/azure-search-documents/src/main/java/ | grep "^D"

Watch for: removed types, renamed constants (need @Deprecated aliases), changed property types, removed method overloads.

Test Recording Notes

If test recordings are stale, update assets.json and re-record. Remove tests for features that no longer exist in the API.

References

File	Contents
references/architecture.md	Source layout, generated vs custom split, key files, packages
references/customizations.md	Per-method customization guide, JavaParser patterns, update triggers

---

Source: Azure/azure-sdk-for-java — distributed by TomeVault.