{"owner":"Azure","repo":"azure-sdk-for-net","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Azure SDK for .NET - AI Agent Guidelines\n\nThis document provides guidelines for AI agents (e.g., GitHub Copilot, MCP-based assistants, LLM-based tools) working with the Azure SDK for .NET repository. It defines safe and effective patterns for agent interactions with this codebase, automation workflows, and development processes.\n\n## Repository Overview\n\n### Purpose and Scope\n\nThe Azure SDK for .NET repository contains:\n- **Data plane client Libraries**: SDKs for interacting with Azure services at application runtime\n- **Management plane Libraries**: SDKs for provisioning and managing Azure resources\n- **Code Generators**: Tools that generate Azure Data Plane and Management Plane SDKs\n- **Build Infrastructure**: Common engineering systems and tooling for SDK development\n\n### Repository Structure\n\n```\n/sdk                                                           # Individual Azure service SDKs\n/eng/packages/http-client-csharp            # Azure Data Plane SDK generator\n/eng/packages/http-client-csharp-mgmt # Azure Management Plane SDK generator\n/eng                                                           # Build, test, and automation infrastructure\n/doc                                                           # Documentation\n```\n\nFor detailed developer instructions, see [CONTRIBUTING.md](https://github.com/Azure/azure-sdk-for-net/blob/main/CONTRIBUTING.md).\n\n## Agent Interaction Guidelines\n\n### Supported Agent Actions\n\nAI agents may assist with the following activities:\n\n#### Code Development\n- **Reading and Understanding Code**: Navigating source files, understanding SDK patterns, and explaining implementations\n- **Code Generation Support**: Assisting with SDK code generation using AutoRest and TypeSpec\n- **Test Creation**: Writing unit tests and integration tests following existing patterns\n- **Bug Fixes**: Identifying and fixing issues in SDK code\n- **API Review**: Preparing code for API reviews and ensuring adherence to design guidelines\n\n#### Documentation\n- **README Updates**: Improving SDK documentation and code samples\n- **Code Comments**: Adding inline documentation\n- **Migration Guides**: Creating guides for breaking changes\n\n#### Automation and Workflows\n- **Build Verification**: Running builds and interpreting results\n- **Test Execution**: Running test suites and analyzing failures\n- **PR Triage**: Summarizing changes and checking CI status\n- **Issue Analysis**: Interpreting bug reports and feature requests\n\n### Safety Boundaries\n\nAI agents **must not**:\n\n- **Commit Secrets**: Never commit credentials, API keys, or sensitive configuration\n- **Bypass Security**: Skip security checks or modify security-critical code without human review\n- **Auto-merge PRs**: Merge pull requests without proper human approval\n- **Modify CI/CD Pipelines**: Change GitHub Actions workflows without explicit permission\n- **Delete Test Coverage**: Remove or disable existing tests unless explicitly instructed\n- **Break API Compatibility**: Introduce breaking changes in GA libraries without explicit design approval\n\nAI agents **should be cautious** when:\n\n- Modifying generated code — **never** update generated code without running the generator to regenerate it\n- Making changes to shared infrastructure in `/eng` — **never** do this unless explicitly asked\n- Updating package dependencies (requires dependency management approval)\n- Changing public APIs (requires API review)\n\n## Key Workflows\n\n### Building and Testing\n\n#### Client Libraries\n\n```powershell\n# Build a specific service\ncd sdk/eventhub\ndotnet build\n\n# Run tests (live tests are excluded by default)\ndotnet test\n\n# Run tests (explicitly skip live tests)\ndotnet test --filter TestCategory!=Live\n\n# Build and test via service.proj\ndotnet build eng/service.proj /p:ServiceDirectory=eventhub\ndotnet test eng/service.proj /p:ServiceDirectory=eventhub --filter TestCategory!=Live\n```\n\n#### Management Libraries\n\n```powershell\n# Build a specific management library\nmsbuild eng/mgmt.proj /p:scope=Compute\n\n# Run tests\nmsbuild eng/mgmt.proj /t:RunTests /p:scope=Compute\n\n# Create NuGet package\nmsbuild eng/mgmt.proj /t:CreateNugetPackage /p:scope=Compute\n```\n\n#### Full Repository Build\n\n```powershell\n# Build entire repository\ndotnet build build.proj\n\n# Build specific scope\ndotnet build build.proj /p:Scope=servicebus\n```\n\n### Code Generation\n\n#### Data Plane SDK Generation (AutoRest)\n\n```powershell\n# Generate code for a data plane SDK\ncd sdk/<service>/<project>/src\ndotnet build /t:GenerateCode -v d\n```\n\n#### Azure Generator (TypeSpec)\n\n```powershell\n# Install dependencies\ncd eng/packages/http-client-csharp\nnpm install\n\n# Generate test projects\n./eng/scripts/Generate.ps1\n```\n\n#### Azure Management Generator\n\n```powershell\n# Install dependencies\ncd eng/packages/http-client-csharp-mgmt\nnpm install\n\n# Generate test projects\n./eng/scripts/Generate.ps1\n```\n\n### API Review and Public API Changes\n\nWhen making public API changes:\n\n```powershell\n# Export API for review\neng/scripts/Export-API.ps1 <service-directory>\n\n# Example\neng/scripts/Export-API.ps1 tables\n```\n\nThis generates API listing files in the format: `sdk/<service>/<project>/api/<project>.<framework>.cs`\n\n### Updating Code Snippets\n\n```powershell\n# Update snippets in markdown documentation\neng/scripts/Update-Snippets.ps1 <service-directory>\n\n# Example\neng/scripts/Update-Snippets.ps1 keyvault\n```\n\n### SDK Release Workflows\n\n#### Check Package Release Readiness\n\n```powershell\n# Verify package is ready for release\n# Checks: API review status, changelog, package name approval, release date\nCheckPackageReleaseReadiness -PackageName <package-name>\n```\n\n#### Release Package\n\n```powershell\n# Trigger release pipeline\nReleasePackage -PackageName <package-name> -Language dotnet\n```\n\n#### Prepare Release\n\n```powershell\n# Update version and changelog for release\n./eng/common/scripts/Prepare-Release.ps1 <PackageName> [<ServiceDirectory>] [<ReleaseDate>]\n```\n\n## Development Prerequisites\n\n### Required Tools\n\n- **.NET 10.0.103 SDK** (or higher within 10.0.* band)\n- **PowerShell 7+** for scripts and code generation\n- **Node.js 22.x.x** for TypeSpec and code generation\n- **Git** with proper line ending configuration (see Configuration section below)\n\n### Configuration\n\n#### Line Endings\n- **Windows**: `core.autocrlf=true` (Checkout Windows-style, commit Unix-style)\n- **Linux/macOS**: `core.autocrlf=input` (Checkout as-is, commit Unix-style)\n\n#### Path Length (Windows)\nClone to short paths (e.g., `C:\\git`) to avoid 260-character path limit. Paths in the repo are kept under 210 characters.\n\n## Common Patterns and Conventions\n\n### Package Naming\n\n- **Client Libraries**: `Azure.<NamespaceGroup>.<ServiceName>` (e.g., `Azure.Storage.Blobs`. See [the guidelines](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-namespace-naming) for approved group names)\n- **Management Libraries**: `Azure.ResourceManager.<ResourceProvider>` (e.g., `Azure.ResourceManager.Compute`)\n- **Legacy Libraries**: `Microsoft.Azure.*` (previous generation; also includes current bridge/integration packages and libraries with unusual dependencies)\n\n### Target Frameworks\n\n- **Client Libraries**: Use `$(RequiredTargetFrameworks)` from `eng/Directory.Build.Data.props`\n- **Management Libraries**: Use `$(SdkTargetFx)` from `AzSdk.reference.props`\n\n### Dependency Management\n\nPackage versions are centrally managed in `eng/Packages.Data.props`. When adding dependencies:\n1. Ensure an `<Update>` reference with version exists in `Packages.Data.props`\n2. Add `<Include>` reference without version in your `.csproj`\n3. Contact azuresdkengsysteam@microsoft.com for version changes\n\n### Testing Standards\n\n- **Unit Tests**: Required for all code changes\n- **Live Tests**: Should be recorded using [Azure.Core.TestFramework](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core.TestFramework/README.md). Note: Newer libraries based on System.ClientModel use the unbranded generator and [Microsoft.ClientModel.TestFramework](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Microsoft.ClientModel.TestFramework/README.md) instead.\n- **Test Categories**: Use `TestCategory!=Live` filter to skip live tests\n- **Code Coverage**: Run with `/p:CollectCoverage=true`\n\n> **Note**: The AutoRest/TypeSpec code generation workflow described in this document applies primarily to HTTP/REST-based client libraries. AMQP or MQTT-based libraries (e.g., Event Hubs, Service Bus, SignalR) do not use this generation process and have different development patterns.\n\n## SDK-Specific Automation\n\n### Continuous Integration\n\n- **Client Libraries**: `sdk/service/ci.yml` files define CI for each service\n- **Management Libraries**: `sdk/resourcemanager/ci.mgmt.yml` for management plane\n- **CI Updates**: Run `eng/scripts/Update-Mgmt-CI.ps1` after adding management libraries\n\n### API Compatibility Verification\n\nGA libraries use ApiCompat tool to enforce API compatibility:\n- Set `ApiCompatVersion` property to last GA version\n- Tool automatically verifies no breaking changes on build\n- Breaking changes fail CI for GA libraries\n\n### Generated Code\n\n- Generated code resides in `Generated/` folders\n- Customizations go in `Customizations/` folders\n- Use `generate.cmd` or `generate.ps1` to regenerate\n- **Never manually edit generated code** - fix the generator or add customizations\n\n### Source Link and Debugging\n\nLibraries have source link enabled:\n- Enable Microsoft Symbol Servers in Visual Studio\n- Disable \"Just My Code\" to step into SDK code\n- Useful for debugging Azure.Core and other dependencies\n\n## Agent-Specific Tools and MCP\n\n### MCP Server Requirements\n\nTo use MCP (Model Context Protocol) tool calls:\n- **PowerShell must be installed** ([Installation Guide](https://learn.microsoft.com/powershell/scripting/install/installing-powershell))\n- Restart IDE after installation to use MCP server\n\n### Available MCP Tools\n\n- `CheckPackageReleaseReadiness`: Verify package release readiness\n- `ReleasePackage`: Trigger package release pipeline\n- `azsdk_package_generate_code`: Generate SDK from TypeSpec locally\n- `azsdk_package_build_code`: Build/compile SDK locally\n\nSee [eng/common/instructions/azsdk-tools/](https://github.com/Azure/azure-sdk-for-net/blob/main/eng/common/instructions/azsdk-tools/) for detailed tool documentation.\n\n## Additional Resources\n\n### Key Documentation\n\n- **[CONTRIBUTING.md](https://github.com/Azure/azure-sdk-for-net/blob/main/CONTRIBUTING.md)**: Complete contribution guide\n- **[README.md](https://github.com/Azure/azure-sdk-for-net/blob/main/README.md)**: Repository overview and getting started\n- **[Azure SDK Design Guidelines for .NET](https://azure.github.io/azure-sdk/dotnet/guidelines/)**: Design principles\n- **[Versioning](https://github.com/Azure/azure-sdk-for-net/blob/main/doc/dev/Versioning.md)**: Versioning strategy\n- **[Breaking Change Rules](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/breaking-change-rules.md)**: Breaking change policy\n\n### Agent Instructions\n\nThis repository includes agent-specific instructions in `.github/copilot-instructions.md` for GitHub Copilot integration. For the most current Copilot-specific guidance, refer to:\n\n**[.github/copilot-instructions.md](https://github.com/Azure/azure-sdk-for-net/blob/main/.github/copilot-instructions.md)**\n\n### Community and Support\n\n- **GitHub Issues**: [Report bugs or request features](https://github.com/Azure/azure-sdk-for-net/issues/new/choose)\n- **Stack Overflow**: Tag questions with `azure` and `.net`\n- **Gitter Chat**: [azure/azure-sdk-for-net](https://gitter.im/azure/azure-sdk-for-net)\n\n## Security and Privacy\n\n### Reporting Security Issues\n\n**Never** open public GitHub issues for security vulnerabilities. Report privately to:\n- **Email**: secure@microsoft.com\n- **MSRC Portal**: [https://www.microsoft.com/msrc/faqs-report-an-issue](https://www.microsoft.com/msrc/faqs-report-an-issue)\n\n### Data Collection and Telemetry\n\nThe Azure SDK collects telemetry by default:\n- Disable per-client: Set `IsTelemetryEnabled=false` in client options\n- Disable globally: Set environment variable `AZURE_TELEMETRY_DISABLED=true`\n- See [Telemetry Guidelines](https://azure.github.io/azure-sdk/general_azurecore.html#telemetry-policy)\n\n## Code of Conduct\n\nThis project follows the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).\n\nFor questions, contact [opencode@microsoft.com](mailto:opencode@microsoft.com).\n\n## License\n\nThis repository is licensed under the MIT License. See [LICENSE.txt](https://github.com/Azure/azure-sdk-for-net/blob/main/LICENSE.txt).\n\n---\n\n**Note**: This document follows the AGENTS.md standards for AI agent documentation in open source repositories.\n"},"files":{"AGENTS.md":"# Azure SDK for .NET - AI Agent Guidelines\n\nThis document provides guidelines for AI agents (e.g., GitHub Copilot, MCP-based assistants, LLM-based tools) working with the Azure SDK for .NET repository. It defines safe and effective patterns for agent interactions with this codebase, automation workflows, and development processes.\n\n## Repository Overview\n\n### Purpose and Scope\n\nThe Azure SDK for .NET repository contains:\n- **Data plane client Libraries**: SDKs for interacting with Azure services at application runtime\n- **Management plane Libraries**: SDKs for provisioning and managing Azure resources\n- **Code Generators**: Tools that generate Azure Data Plane and Management Plane SDKs\n- **Build Infrastructure**: Common engineering systems and tooling for SDK development\n\n### Repository Structure\n\n```\n/sdk                                                           # Individual Azure service SDKs\n/eng/packages/http-client-csharp            # Azure Data Plane SDK generator\n/eng/packages/http-client-csharp-mgmt # Azure Management Plane SDK generator\n/eng                                                           # Build, test, and automation infrastructure\n/doc                                                           # Documentation\n```\n\nFor detailed developer instructions, see [CONTRIBUTING.md](https://github.com/Azure/azure-sdk-for-net/blob/main/CONTRIBUTING.md).\n\n## Agent Interaction Guidelines\n\n### Supported Agent Actions\n\nAI agents may assist with the following activities:\n\n#### Code Development\n- **Reading and Understanding Code**: Navigating source files, understanding SDK patterns, and explaining implementations\n- **Code Generation Support**: Assisting with SDK code generation using AutoRest and TypeSpec\n- **Test Creation**: Writing unit tests and integration tests following existing patterns\n- **Bug Fixes**: Identifying and fixing issues in SDK code\n- **API Review**: Preparing code for API reviews and ensuring adherence to design guidelines\n\n#### Documentation\n- **README Updates**: Improving SDK documentation and code samples\n- **Code Comments**: Adding inline documentation\n- **Migration Guides**: Creating guides for breaking changes\n\n#### Automation and Workflows\n- **Build Verification**: Running builds and interpreting results\n- **Test Execution**: Running test suites and analyzing failures\n- **PR Triage**: Summarizing changes and checking CI status\n- **Issue Analysis**: Interpreting bug reports and feature requests\n\n### Safety Boundaries\n\nAI agents **must not**:\n\n- **Commit Secrets**: Never commit credentials, API keys, or sensitive configuration\n- **Bypass Security**: Skip security checks or modify security-critical code without human review\n- **Auto-merge PRs**: Merge pull requests without proper human approval\n- **Modify CI/CD Pipelines**: Change GitHub Actions workflows without explicit permission\n- **Delete Test Coverage**: Remove or disable existing tests unless explicitly instructed\n- **Break API Compatibility**: Introduce breaking changes in GA libraries without explicit design approval\n\nAI agents **should be cautious** when:\n\n- Modifying generated code — **never** update generated code without running the generator to regenerate it\n- Making changes to shared infrastructure in `/eng` — **never** do this unless explicitly asked\n- Updating package dependencies (requires dependency management approval)\n- Changing public APIs (requires API review)\n\n## Key Workflows\n\n### Building and Testing\n\n#### Client Libraries\n\n```powershell\n# Build a specific service\ncd sdk/eventhub\ndotnet build\n\n# Run tests (live tests are excluded by default)\ndotnet test\n\n# Run tests (explicitly skip live tests)\ndotnet test --filter TestCategory!=Live\n\n# Build and test via service.proj\ndotnet build eng/service.proj /p:ServiceDirectory=eventhub\ndotnet test eng/service.proj /p:ServiceDirectory=eventhub --filter TestCategory!=Live\n```\n\n#### Management Libraries\n\n```powershell\n# Build a specific management library\nmsbuild eng/mgmt.proj /p:scope=Compute\n\n# Run tests\nmsbuild eng/mgmt.proj /t:RunTests /p:scope=Compute\n\n# Create NuGet package\nmsbuild eng/mgmt.proj /t:CreateNugetPackage /p:scope=Compute\n```\n\n#### Full Repository Build\n\n```powershell\n# Build entire repository\ndotnet build build.proj\n\n# Build specific scope\ndotnet build build.proj /p:Scope=servicebus\n```\n\n### Code Generation\n\n#### Data Plane SDK Generation (AutoRest)\n\n```powershell\n# Generate code for a data plane SDK\ncd sdk/<service>/<project>/src\ndotnet build /t:GenerateCode -v d\n```\n\n#### Azure Generator (TypeSpec)\n\n```powershell\n# Install dependencies\ncd eng/packages/http-client-csharp\nnpm install\n\n# Generate test projects\n./eng/scripts/Generate.ps1\n```\n\n#### Azure Management Generator\n\n```powershell\n# Install dependencies\ncd eng/packages/http-client-csharp-mgmt\nnpm install\n\n# Generate test projects\n./eng/scripts/Generate.ps1\n```\n\n### API Review and Public API Changes\n\nWhen making public API changes:\n\n```powershell\n# Export API for review\neng/scripts/Export-API.ps1 <service-directory>\n\n# Example\neng/scripts/Export-API.ps1 tables\n```\n\nThis generates API listing files in the format: `sdk/<service>/<project>/api/<project>.<framework>.cs`\n\n### Updating Code Snippets\n\n```powershell\n# Update snippets in markdown documentation\neng/scripts/Update-Snippets.ps1 <service-directory>\n\n# Example\neng/scripts/Update-Snippets.ps1 keyvault\n```\n\n### SDK Release Workflows\n\n#### Check Package Release Readiness\n\n```powershell\n# Verify package is ready for release\n# Checks: API review status, changelog, package name approval, release date\nCheckPackageReleaseReadiness -PackageName <package-name>\n```\n\n#### Release Package\n\n```powershell\n# Trigger release pipeline\nReleasePackage -PackageName <package-name> -Language dotnet\n```\n\n#### Prepare Release\n\n```powershell\n# Update version and changelog for release\n./eng/common/scripts/Prepare-Release.ps1 <PackageName> [<ServiceDirectory>] [<ReleaseDate>]\n```\n\n## Development Prerequisites\n\n### Required Tools\n\n- **.NET 10.0.103 SDK** (or higher within 10.0.* band)\n- **PowerShell 7+** for scripts and code generation\n- **Node.js 22.x.x** for TypeSpec and code generation\n- **Git** with proper line ending configuration (see Configuration section below)\n\n### Configuration\n\n#### Line Endings\n- **Windows**: `core.autocrlf=true` (Checkout Windows-style, commit Unix-style)\n- **Linux/macOS**: `core.autocrlf=input` (Checkout as-is, commit Unix-style)\n\n#### Path Length (Windows)\nClone to short paths (e.g., `C:\\git`) to avoid 260-character path limit. Paths in the repo are kept under 210 characters.\n\n## Common Patterns and Conventions\n\n### Package Naming\n\n- **Client Libraries**: `Azure.<NamespaceGroup>.<ServiceName>` (e.g., `Azure.Storage.Blobs`. See [the guidelines](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-namespace-naming) for approved group names)\n- **Management Libraries**: `Azure.ResourceManager.<ResourceProvider>` (e.g., `Azure.ResourceManager.Compute`)\n- **Legacy Libraries**: `Microsoft.Azure.*` (previous generation; also includes current bridge/integration packages and libraries with unusual dependencies)\n\n### Target Frameworks\n\n- **Client Libraries**: Use `$(RequiredTargetFrameworks)` from `eng/Directory.Build.Data.props`\n- **Management Libraries**: Use `$(SdkTargetFx)` from `AzSdk.reference.props`\n\n### Dependency Management\n\nPackage versions are centrally managed in `eng/Packages.Data.props`. When adding dependencies:\n1. Ensure an `<Update>` reference with version exists in `Packages.Data.props`\n2. Add `<Include>` reference without version in your `.csproj`\n3. Contact azuresdkengsysteam@microsoft.com for version changes\n\n### Testing Standards\n\n- **Unit Tests**: Required for all code changes\n- **Live Tests**: Should be recorded using [Azure.Core.TestFramework](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core.TestFramework/README.md). Note: Newer libraries based on System.ClientModel use the unbranded generator and [Microsoft.ClientModel.TestFramework](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Microsoft.ClientModel.TestFramework/README.md) instead.\n- **Test Categories**: Use `TestCategory!=Live` filter to skip live tests\n- **Code Coverage**: Run with `/p:CollectCoverage=true`\n\n> **Note**: The AutoRest/TypeSpec code generation workflow described in this document applies primarily to HTTP/REST-based client libraries. AMQP or MQTT-based libraries (e.g., Event Hubs, Service Bus, SignalR) do not use this generation process and have different development patterns.\n\n## SDK-Specific Automation\n\n### Continuous Integration\n\n- **Client Libraries**: `sdk/service/ci.yml` files define CI for each service\n- **Management Libraries**: `sdk/resourcemanager/ci.mgmt.yml` for management plane\n- **CI Updates**: Run `eng/scripts/Update-Mgmt-CI.ps1` after adding management libraries\n\n### API Compatibility Verification\n\nGA libraries use ApiCompat tool to enforce API compatibility:\n- Set `ApiCompatVersion` property to last GA version\n- Tool automatically verifies no breaking changes on build\n- Breaking changes fail CI for GA libraries\n\n### Generated Code\n\n- Generated code resides in `Generated/` folders\n- Customizations go in `Customizations/` folders\n- Use `generate.cmd` or `generate.ps1` to regenerate\n- **Never manually edit generated code** - fix the generator or add customizations\n\n### Source Link and Debugging\n\nLibraries have source link enabled:\n- Enable Microsoft Symbol Servers in Visual Studio\n- Disable \"Just My Code\" to step into SDK code\n- Useful for debugging Azure.Core and other dependencies\n\n## Agent-Specific Tools and MCP\n\n### MCP Server Requirements\n\nTo use MCP (Model Context Protocol) tool calls:\n- **PowerShell must be installed** ([Installation Guide](https://learn.microsoft.com/powershell/scripting/install/installing-powershell))\n- Restart IDE after installation to use MCP server\n\n### Available MCP Tools\n\n- `CheckPackageReleaseReadiness`: Verify package release readiness\n- `ReleasePackage`: Trigger package release pipeline\n- `azsdk_package_generate_code`: Generate SDK from TypeSpec locally\n- `azsdk_package_build_code`: Build/compile SDK locally\n\nSee [eng/common/instructions/azsdk-tools/](https://github.com/Azure/azure-sdk-for-net/blob/main/eng/common/instructions/azsdk-tools/) for detailed tool documentation.\n\n## Additional Resources\n\n### Key Documentation\n\n- **[CONTRIBUTING.md](https://github.com/Azure/azure-sdk-for-net/blob/main/CONTRIBUTING.md)**: Complete contribution guide\n- **[README.md](https://github.com/Azure/azure-sdk-for-net/blob/main/README.md)**: Repository overview and getting started\n- **[Azure SDK Design Guidelines for .NET](https://azure.github.io/azure-sdk/dotnet/guidelines/)**: Design principles\n- **[Versioning](https://github.com/Azure/azure-sdk-for-net/blob/main/doc/dev/Versioning.md)**: Versioning strategy\n- **[Breaking Change Rules](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/breaking-change-rules.md)**: Breaking change policy\n\n### Agent Instructions\n\nThis repository includes agent-specific instructions in `.github/copilot-instructions.md` for GitHub Copilot integration. For the most current Copilot-specific guidance, refer to:\n\n**[.github/copilot-instructions.md](https://github.com/Azure/azure-sdk-for-net/blob/main/.github/copilot-instructions.md)**\n\n### Community and Support\n\n- **GitHub Issues**: [Report bugs or request features](https://github.com/Azure/azure-sdk-for-net/issues/new/choose)\n- **Stack Overflow**: Tag questions with `azure` and `.net`\n- **Gitter Chat**: [azure/azure-sdk-for-net](https://gitter.im/azure/azure-sdk-for-net)\n\n## Security and Privacy\n\n### Reporting Security Issues\n\n**Never** open public GitHub issues for security vulnerabilities. Report privately to:\n- **Email**: secure@microsoft.com\n- **MSRC Portal**: [https://www.microsoft.com/msrc/faqs-report-an-issue](https://www.microsoft.com/msrc/faqs-report-an-issue)\n\n### Data Collection and Telemetry\n\nThe Azure SDK collects telemetry by default:\n- Disable per-client: Set `IsTelemetryEnabled=false` in client options\n- Disable globally: Set environment variable `AZURE_TELEMETRY_DISABLED=true`\n- See [Telemetry Guidelines](https://azure.github.io/azure-sdk/general_azurecore.html#telemetry-policy)\n\n## Code of Conduct\n\nThis project follows the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).\n\nFor questions, contact [opencode@microsoft.com](mailto:opencode@microsoft.com).\n\n## License\n\nThis repository is licensed under the MIT License. See [LICENSE.txt](https://github.com/Azure/azure-sdk-for-net/blob/main/LICENSE.txt).\n\n---\n\n**Note**: This document follows the AGENTS.md standards for AI agent documentation in open source repositories.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Azure SDK for .NET - AI Agent Guidelines\n\nThis document provides guidelines for AI agents (e.g., GitHub Copilot, MCP-based assistants, LLM-based tools) working with the Azure SDK for .NET repository. It defines safe and effective patterns for agent interactions with this codebase, automation workflows, and development processes.\n\n## Repository Overview\n\n### Purpose and Scope\n\nThe Azure SDK for .NET repository contains:\n- **Data plane client Libraries**: SDKs for interacting with Azure services at application runtime\n- **Management plane Libraries**: SDKs for provisioning and managing Azure resources\n- **Code Generators**: Tools that generate Azure Data Plane and Management Plane SDKs\n- **Build Infrastructure**: Common engineering systems and tooling for SDK development\n\n### Repository Structure\n\n```\n/sdk                                                           # Individual Azure service SDKs\n/eng/packages/http-client-csharp            # Azure Data Plane SDK generator\n/eng/packages/http-client-csharp-mgmt # Azure Management Plane SDK generator\n/eng                                                           # Build, test, and automation infrastructure\n/doc                                                           # Documentation\n```\n\nFor detailed developer instructions, see [CONTRIBUTING.md](https://github.com/Azure/azure-sdk-for-net/blob/main/CONTRIBUTING.md).\n\n## Agent Interaction Guidelines\n\n### Supported Agent Actions\n\nAI agents may assist with the following activities:\n\n#### Code Development\n- **Reading and Understanding Code**: Navigating source files, understanding SDK patterns, and explaining implementations\n- **Code Generation Support**: Assisting with SDK code generation using AutoRest and TypeSpec\n- **Test Creation**: Writing unit tests and integration tests following existing patterns\n- **Bug Fixes**: Identifying and fixing issues in SDK code\n- **API Review**: Preparing code for API reviews and ensuring adherence to design guidelines\n\n#### Documentation\n- **README Updates**: Improving SDK documentation and code samples\n- **Code Comments**: Adding inline documentation\n- **Migration Guides**: Creating guides for breaking changes\n\n#### Automation and Workflows\n- **Build Verification**: Running builds and interpreting results\n- **Test Execution**: Running test suites and analyzing failures\n- **PR Triage**: Summarizing changes and checking CI status\n- **Issue Analysis**: Interpreting bug reports and feature requests\n\n### Safety Boundaries\n\nAI agents **must not**:\n\n- **Commit Secrets**: Never commit credentials, API keys, or sensitive configuration\n- **Bypass Security**: Skip security checks or modify security-critical code without human review\n- **Auto-merge PRs**: Merge pull requests without proper human approval\n- **Modify CI/CD Pipelines**: Change GitHub Actions workflows without explicit permission\n- **Delete Test Coverage**: Remove or disable existing tests unless explicitly instructed\n- **Break API Compatibility**: Introduce breaking changes in GA libraries without explicit design approval\n\nAI agents **should be cautious** when:\n\n- Modifying generated code — **never** update generated code without running the generator to regenerate it\n- Making changes to shared infrastructure in `/eng` — **never** do this unless explicitly asked\n- Updating package dependencies (requires dependency management approval)\n- Changing public APIs (requires API review)\n\n## Key Workflows\n\n### Building and Testing\n\n#### Client Libraries\n\n```powershell\n# Build a specific service\ncd sdk/eventhub\ndotnet build\n\n# Run tests (live tests are excluded by default)\ndotnet test\n\n# Run tests (explicitly skip live tests)\ndotnet test --filter TestCategory!=Live\n\n# Build and test via service.proj\ndotnet build eng/service.proj /p:ServiceDirectory=eventhub\ndotnet test eng/service.proj /p:ServiceDirectory=eventhub --filter TestCategory!=Live\n```\n\n#### Management Libraries\n\n```powershell\n# Build a specific management library\nmsbuild eng/mgmt.proj /p:scope=Compute\n\n# Run tests\nmsbuild eng/mgmt.proj /t:RunTests /p:scope=Compute\n\n# Create NuGet package\nmsbuild eng/mgmt.proj /t:CreateNugetPackage /p:scope=Compute\n```\n\n#### Full Repository Build\n\n```powershell\n# Build entire repository\ndotnet build build.proj\n\n# Build specific scope\ndotnet build build.proj /p:Scope=servicebus\n```\n\n### Code Generation\n\n#### Data Plane SDK Generation (AutoRest)\n\n```powershell\n# Generate code for a data plane SDK\ncd sdk/<service>/<project>/src\ndotnet build /t:GenerateCode -v d\n```\n\n#### Azure Generator (TypeSpec)\n\n```powershell\n# Install dependencies\ncd eng/packages/http-client-csharp\nnpm install\n\n# Generate test projects\n./eng/scripts/Generate.ps1\n```\n\n#### Azure Management Generator\n\n```powershell\n# Install dependencies\ncd eng/packages/http-client-csharp-mgmt\nnpm install\n\n# Generate test projects\n./eng/scripts/Generate.ps1\n```\n\n### API Review and Public API Changes\n\nWhen making public API changes:\n\n```powershell\n# Export API for review\neng/scripts/Export-API.ps1 <service-directory>\n\n# Example\neng/scripts/Export-API.ps1 tables\n```\n\nThis generates API listing files in the format: `sdk/<service>/<project>/api/<project>.<framework>.cs`\n\n### Updating Code Snippets\n\n```powershell\n# Update snippets in markdown documentation\neng/scripts/Update-Snippets.ps1 <service-directory>\n\n# Example\neng/scripts/Update-Snippets.ps1 keyvault\n```\n\n### SDK Release Workflows\n\n#### Check Package Release Readiness\n\n```powershell\n# Verify package is ready for release\n# Checks: API review status, changelog, package name approval, release date\nCheckPackageReleaseReadiness -PackageName <package-name>\n```\n\n#### Release Package\n\n```powershell\n# Trigger release pipeline\nReleasePackage -PackageName <package-name> -Language dotnet\n```\n\n#### Prepare Release\n\n```powershell\n# Update version and changelog for release\n./eng/common/scripts/Prepare-Release.ps1 <PackageName> [<ServiceDirectory>] [<ReleaseDate>]\n```\n\n## Development Prerequisites\n\n### Required Tools\n\n- **.NET 10.0.103 SDK** (or higher within 10.0.* band)\n- **PowerShell 7+** for scripts and code generation\n- **Node.js 22.x.x** for TypeSpec and code generation\n- **Git** with proper line ending configuration (see Configuration section below)\n\n### Configuration\n\n#### Line Endings\n- **Windows**: `core.autocrlf=true` (Checkout Windows-style, commit Unix-style)\n- **Linux/macOS**: `core.autocrlf=input` (Checkout as-is, commit Unix-style)\n\n#### Path Length (Windows)\nClone to short paths (e.g., `C:\\git`) to avoid 260-character path limit. Paths in the repo are kept under 210 characters.\n\n## Common Patterns and Conventions\n\n### Package Naming\n\n- **Client Libraries**: `Azure.<NamespaceGroup>.<ServiceName>` (e.g., `Azure.Storage.Blobs`. See [the guidelines](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-namespace-naming) for approved group names)\n- **Management Libraries**: `Azure.ResourceManager.<ResourceProvider>` (e.g., `Azure.ResourceManager.Compute`)\n- **Legacy Libraries**: `Microsoft.Azure.*` (previous generation; also includes current bridge/integration packages and libraries with unusual dependencies)\n\n### Target Frameworks\n\n- **Client Libraries**: Use `$(RequiredTargetFrameworks)` from `eng/Directory.Build.Data.props`\n- **Management Libraries**: Use `$(SdkTargetFx)` from `AzSdk.reference.props`\n\n### Dependency Management\n\nPackage versions are centrally managed in `eng/Packages.Data.props`. When adding dependencies:\n1. Ensure an `<Update>` reference with version exists in `Packages.Data.props`\n2. Add `<Include>` reference without version in your `.csproj`\n3. Contact azuresdkengsysteam@microsoft.com for version changes\n\n### Testing Standards\n\n- **Unit Tests**: Required for all code changes\n- **Live Tests**: Should be recorded using [Azure.Core.TestFramework](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core.TestFramework/README.md). Note: Newer libraries based on System.ClientModel use the unbranded generator and [Microsoft.ClientModel.TestFramework](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Microsoft.ClientModel.TestFramework/README.md) instead.\n- **Test Categories**: Use `TestCategory!=Live` filter to skip live tests\n- **Code Coverage**: Run with `/p:CollectCoverage=true`\n\n> **Note**: The AutoRest/TypeSpec code generation workflow described in this document applies primarily to HTTP/REST-based client libraries. AMQP or MQTT-based libraries (e.g., Event Hubs, Service Bus, SignalR) do not use this generation process and have different development patterns.\n\n## SDK-Specific Automation\n\n### Continuous Integration\n\n- **Client Libraries**: `sdk/service/ci.yml` files define CI for each service\n- **Management Libraries**: `sdk/resourcemanager/ci.mgmt.yml` for management plane\n- **CI Updates**: Run `eng/scripts/Update-Mgmt-CI.ps1` after adding management libraries\n\n### API Compatibility Verification\n\nGA libraries use ApiCompat tool to enforce API compatibility:\n- Set `ApiCompatVersion` property to last GA version\n- Tool automatically verifies no breaking changes on build\n- Breaking changes fail CI for GA libraries\n\n### Generated Code\n\n- Generated code resides in `Generated/` folders\n- Customizations go in `Customizations/` folders\n- Use `generate.cmd` or `generate.ps1` to regenerate\n- **Never manually edit generated code** - fix the generator or add customizations\n\n### Source Link and Debugging\n\nLibraries have source link enabled:\n- Enable Microsoft Symbol Servers in Visual Studio\n- Disable \"Just My Code\" to step into SDK code\n- Useful for debugging Azure.Core and other dependencies\n\n## Agent-Specific Tools and MCP\n\n### MCP Server Requirements\n\nTo use MCP (Model Context Protocol) tool calls:\n- **PowerShell must be installed** ([Installation Guide](https://learn.microsoft.com/powershell/scripting/install/installing-powershell))\n- Restart IDE after installation to use MCP server\n\n### Available MCP Tools\n\n- `CheckPackageReleaseReadiness`: Verify package release readiness\n- `ReleasePackage`: Trigger package release pipeline\n- `azsdk_package_generate_code`: Generate SDK from TypeSpec locally\n- `azsdk_package_build_code`: Build/compile SDK locally\n\nSee [eng/common/instructions/azsdk-tools/](https://github.com/Azure/azure-sdk-for-net/blob/main/eng/common/instructions/azsdk-tools/) for detailed tool documentation.\n\n## Additional Resources\n\n### Key Documentation\n\n- **[CONTRIBUTING.md](https://github.com/Azure/azure-sdk-for-net/blob/main/CONTRIBUTING.md)**: Complete contribution guide\n- **[README.md](https://github.com/Azure/azure-sdk-for-net/blob/main/README.md)**: Repository overview and getting started\n- **[Azure SDK Design Guidelines for .NET](https://azure.github.io/azure-sdk/dotnet/guidelines/)**: Design principles\n- **[Versioning](https://github.com/Azure/azure-sdk-for-net/blob/main/doc/dev/Versioning.md)**: Versioning strategy\n- **[Breaking Change Rules](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/breaking-change-rules.md)**: Breaking change policy\n\n### Agent Instructions\n\nThis repository includes agent-specific instructions in `.github/copilot-instructions.md` for GitHub Copilot integration. For the most current Copilot-specific guidance, refer to:\n\n**[.github/copilot-instructions.md](https://github.com/Azure/azure-sdk-for-net/blob/main/.github/copilot-instructions.md)**\n\n### Community and Support\n\n- **GitHub Issues**: [Report bugs or request features](https://github.com/Azure/azure-sdk-for-net/issues/new/choose)\n- **Stack Overflow**: Tag questions with `azure` and `.net`\n- **Gitter Chat**: [azure/azure-sdk-for-net](https://gitter.im/azure/azure-sdk-for-net)\n\n## Security and Privacy\n\n### Reporting Security Issues\n\n**Never** open public GitHub issues for security vulnerabilities. Report privately to:\n- **Email**: secure@microsoft.com\n- **MSRC Portal**: [https://www.microsoft.com/msrc/faqs-report-an-issue](https://www.microsoft.com/msrc/faqs-report-an-issue)\n\n### Data Collection and Telemetry\n\nThe Azure SDK collects telemetry by default:\n- Disable per-client: Set `IsTelemetryEnabled=false` in client options\n- Disable globally: Set environment variable `AZURE_TELEMETRY_DISABLED=true`\n- See [Telemetry Guidelines](https://azure.github.io/azure-sdk/general_azurecore.html#telemetry-policy)\n\n## Code of Conduct\n\nThis project follows the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).\n\nFor questions, contact [opencode@microsoft.com](mailto:opencode@microsoft.com).\n\n## License\n\nThis repository is licensed under the MIT License. See [LICENSE.txt](https://github.com/Azure/azure-sdk-for-net/blob/main/LICENSE.txt).\n\n---\n\n**Note**: This document follows the AGENTS.md standards for AI agent documentation in open source repositories.\n","category":"root","tokens":3185}]}