pre-commit-checks
Pre-commit validation checks for azure-sdk-for-net. Use this before committing or pushing changes to SDK packages. Runs dotnet format, exports public API listings, updates snippets, and regenerates code as needed.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 6.1k
- Forks
- 5.2k
01 前言 Front Matter
- name
- pre-commit-checks
- description
- Pre-commit validation checks for azure-sdk-for-net. Use this before committing or pushing changes to SDK packages. Runs dotnet format, exports public API listings, updates snippets, and regenerates code as needed.
03 SKILL.md 正文
Pre-Commit Validation Checks
Run these checks after making changes to SDK packages under sdk/ and before staging, committing, or pushing. These steps may produce additional file changes that must be included in the commit.
General rule: Steps 3–5 are conditional to save time, but if you are unsure whether a step is needed, always run it. It is better to run an unnecessary script than to miss a required regeneration.
1. Determine scope from changed files
- Derive the changed file list from
git status --porcelain(or by combininggit diff --name-only HEADwithgit ls-files -o --exclude-standard) so that untracked (new) files are included. - From the changed file list, extract all unique ServiceDirectories — the first path segment after
sdk/(e.g.,sdk/storage/...→storage,sdk/ai/...→ai). - For each ServiceDirectory, identify all affected packages = distinct
sdk/{ServiceDirectory}/{PackageName}/paths. - For each affected package, identify:
- All csproj files that had changes beneath them (src, tests, samples, perf, stress, or any other project type).
- The src csproj specifically =
sdk/{service}/{package}/src/{Package}.csproj— this is used for GenerateCode.
- The remaining steps must be run for each affected project/ServiceDirectory. If changes span multiple ServiceDirectories or packages, run for each one.
2. Run dotnet format (for every changed csproj)
For every csproj that had files change beneath it — src, tests, samples, perf, stress, or any other project type — run:
dotnet format <path-to-changed.csproj>
Identify affected csproj files by looking at the full changed file list: include any project where either (a) there is a changed .cs file with that .csproj as its nearest parent, or (b) the .csproj itself changed, or files such as .props, .targets, or .md changed under that project. This fixes style/formatting issues and may modify .cs files.
3. Conditionally run dotnet build /t:GenerateCode (per src csproj)
Exclusion: Skip this step entirely for the provisioning service directory. Provisioning libraries use their own generator and are not generated via TypeSpec/AutoRest.
Trigger condition — for each affected package's src csproj: Run this if ANY of the following files are in the changed file list:
- Any file matching
sdk/{service}/{package}/src/Generated/** sdk/{service}/{package}/tsp-location.yamlsdk/{service}/{package}/src/autorest.md- Any
.csfile undersdk/{service}/{package}/src/where aCodeGen*attribute was added, removed, or modified (e.g.,CodeGenType,CodeGenModel,CodeGenClient,CodeGenMember,CodeGenSuppress,CodeGenSerialization,CodeGenVisibility). These attributes in custom (non-generated) code influence the generated output.
Important: Do not manually edit files under src/Generated/. Changes to generated code should only come from running the GenerateCode target.
Command:
dotnet build sdk/{service}/{package}/src/{Package}.csproj /t:GenerateCode
This regenerates code from TypeSpec/AutoRest specs. It may modify files under src/Generated/.
4. Conditionally run Export-API.ps1 (per ServiceDirectory)
Trigger condition — per ServiceDirectory: Run this if ANY of the following are true for ANY affected package within this ServiceDirectory:
- Step 3 above ran for any package in this ServiceDirectory (generated code may affect public API).
- Changed
.csfiles undersdk/{service}/{package}/src/for any package in this ServiceDirectory contain public API surface changes. To determine this, inspect the diffs for:- New, removed, or renamed
publicorprotectedtypes (class,interface,struct,enum,record). - New, removed, or changed signatures of
publicorprotectedmembers (methods, properties, constructors, events, fields). - Visibility changes (e.g.,
internal→public). - Changes to base classes or implemented interfaces on public types.
- New
.csfiles undersrc/that containpublictypes.
- New, removed, or renamed
Skip Export-API if changes are limited to:
- Method body implementations (no signature changes).
internalorprivatemembers only.- XML doc comments or code comments.
.csprojconfiguration changes.
Command:
eng\scripts\Export-API.ps1 {ServiceDirectory}
This regenerates API listing files under sdk/{service}/{package}/api/*.cs. Uses dotnet build /t:ExportApi internally.
Note: Export-API operates at the ServiceDirectory level (not per-csproj), so run it once per affected ServiceDirectory.
5. Conditionally run Update-Snippets.ps1 (per ServiceDirectory)
Trigger condition — for each affected ServiceDirectory: Run this if ANY of the following are true:
- Changed
*.mdfiles undersdk/{service}/contain snippet references (```C# Snippet:markers). - Changed
.csfiles contain snippet regions (#region Snippet:).
Command:
eng\scripts\Update-Snippets.ps1 {ServiceDirectory}
Note: Update-Snippets operates at the ServiceDirectory level (not per-csproj), so run it once per affected ServiceDirectory.
This runs snippet-generator to sync code snippets into markdown files. May modify *.md and *.cs files.
6. Verify and include all changes
- After running all applicable steps for all affected projects and ServiceDirectories, check for new/modified files with
git status. - All changes produced by these steps must be included in the commit.
- Do NOT commit if any of the above steps failed.
Execution order
Run the following steps in this order, respecting their scope (per package vs per ServiceDirectory):
dotnet formatfirst — run on all changed csproj files (src, tests, etc.) for each affected package.GenerateCodesecond — per src csproj, regenerates from specs (may override format changes in Generated/) for each affected package.Export-APIthird — run once per affected ServiceDirectory, after all GenerateCode runs for packages in that ServiceDirectory are complete; captures the final public API surface after generation.Update-Snippetsfourth — run once per affected ServiceDirectory, after Export-API; captures any snippet changes from all prior steps.
When multiple packages/ServiceDirectories are affected, run steps 1–2 for each affected package, then steps 3–4 once per affected ServiceDirectory. Step 6 (verify) runs once at the end.
04 同仓库更多 Skills
update-chat-api
Use when: updating, exporting, refreshing, or validating the public API baseline for Azure.Messaging.WebPubSub.Chat after a public API change.
search-documents
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.
search-documents-version-diff
Diff the current Azure.Search.Documents public API surface against a previous published version and detect preview-to-preview regressions where the SDK customization layer was not bubbled up after a TypeSpec change. Use whenever the user asks to compare Azure.Search.Documents betas, verify no Azure.Search.Documents preview features dropped, regression audit between Azure.Search.Documents versions, sanity-check a release branch for Azure.Search.Documents, or investigate a missing Azure.Search.Documents preview feature — even if they don't say the word "diff". Specifically catches dropped wrappers (QueryAnswer/QueryCaption/QueryRewrites style), lost SearchOptions aggregator redirectors, `@@access("internal")` flips, deleted-instead-of-gated `#if AZURE_SEARCH_PREVIEW` blocks, dropped `ServiceVersion` enum values, and convenience-to-protocol downgrades.
search-documents-typespec-validation
TypeSpec validation skill for Azure.Search.Documents SDK. Performs a COMPLETE validation of ALL operations, ALL models, ALL enums, and ALL properties against the TypeSpec definition at any pinned commit. Works for any API version. Generates a full gap report: missing features, extra features, naming mismatches, and recommended fix location. WHEN: "validate Azure.Search.Documents SDK against TypeSpec", "detect Azure.Search.Documents typespec feature gaps", "what is missing from the Azure.Search.Documents SDK", "compare Azure.Search.Documents SDK to spec", "full spec coverage audit for Azure.Search.Documents". Do NOT use for version-to-version diff or regression detection — use search-documents-version-diff instead.
test-skill_file
Roll dice using a random number generator.
roll-dice
Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.