| 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 mismatchesincludeOldApiVersions() -- can duplicate enum constants the generator now producesaddSearchAudienceScopeHandling() -- 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.
- Check
getLatest() returns the new version
- In
includeOldApiVersions():
- Remove any version the generator now produces (prevents duplicates)
- Add the previous latest version if not already produced by the generator
- Verify all expected old versions are present
Detect Breaking Changes
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
Source: Azure/azure-sdk-for-java — distributed by TomeVault.
