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