 管理平面 SDK 编排 Azure SQL 资源)
使用 Azure.ResourceManager.Sql (.NET) 管理平面 SDK 编排 Azure SQL 资源【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills导读本文基于 agentic-awesome-skills 仓库中的azure-resource-manager-sql-dotnet技能文档系统讲解在 .NET 应用中通过Azure.ResourceManager.SqlAzure Resource Manager 管理平面 SDK以编程方式创建、配置与治理 Azure SQL Server、数据库、弹性池、防火墙规则与故障转移组等资源。你将掌握从环境配置、DefaultAzureCredential认证、资源层级导航到完整 CRUD 工作流、SKU 选型、错误处理与生产级最佳实践的一整套实操能力可直接用于编写自动化部署脚本、运维工具或 CI/CD 中的 SQL 资源编排步骤。管理平面与数据平面先分清 SDK 的边界在动手写代码前必须先理解Azure.ResourceManager.Sql在整个 Azure SQL 体系中的定位。该技能文档开篇就明确强调了管理平面Management Plane与数据平面Data Plane的严格区分管理平面 SDKAzure.ResourceManager.Sql负责“建”和“管”资源——创建 SQL Server、创建数据库、管理弹性池、配置防火墙规则、管理故障转移组、设置审计策略与透明数据加密TDE等。它操作的是一整套 ARM 资源对象。数据平面 SDKMicrosoft.Data.SqlClient负责“用”数据——建立连接、执行查询、调用存储过程、管理事务。它直接面向*.database.windows.net上的数据库引擎。两者的职责边界决定了它们不能互相替代你无法用Azure.ResourceManager.Sql执行SELECT也无法用Microsoft.Data.SqlClient创建弹性池。实际项目中通常组合使用先用管理平面 SDK 完成资源编排再用数据平面 SDK 执行初始化脚本或业务查询。仓库中与该技能同属 Azure 系列的 azure-sql 等技能文档可帮助你进一步理解 Azure SQL 生态中各 SDK 的协作关系。安装与环境变量配置安装 NuGet 包dotnet add package Azure.ResourceManager.Sql dotnet add package Azure.IdentityAzure.ResourceManager.Sql本技能的核心包提供全部 SQL 管理资源类型。Azure.Identity提供DefaultAzureCredential等身份认证组件是使用 ARM SDK 的必需配套。技能文档标注的当前版本信息为Stable v1.3.0、Preview v1.4.0-beta.3。安装前可通过dotnet list package或 NuGet 官方源确认实际可用版本并优先选择与你的 .NET 目标框架如 net8.0/net9.0兼容的稳定版本。环境变量AZURE_SUBSCRIPTION_IDyour-subscription-id # For service principal auth (optional) AZURE_TENANT_IDtenant-id AZURE_CLIENT_IDclient-id AZURE_CLIENT_SECRETclient-secretAZURE_SUBSCRIPTION_ID必填。用于构造订阅资源标识符/subscriptions/{id}是后续一切资源操作的作用域起点。AZURE_TENANT_ID/AZURE_CLIENT_ID/AZURE_CLIENT_SECRET可选仅在采用服务主体Service Principal认证时需要。DefaultAzureCredential会自动读取这些变量完成服务主体认证若在本地开发环境则优先使用 Visual Studio / Azure CLI 登录凭据无需配置这三项。认证始终使用 DefaultAzureCredential管理平面 SDK 的入口是ArmClient而构建它的第一步是获得一个可信凭据using Azure.Identity; using Azure.ResourceManager; using Azure.ResourceManager.Sql; // Always use DefaultAzureCredential var credential new DefaultAzureCredential(); var armClient new ArmClient(credential); // Get subscription var subscriptionId Environment.GetEnvironmentVariable(AZURE_SUBSCRIPTION_ID); var subscription armClient.GetSubscriptionResource( new ResourceIdentifier($/subscriptions/{subscriptionId}));几点需要理解的关键机制DefaultAzureCredential的链式尝试它会按顺序尝试多种凭据来源环境变量服务主体 → Azure CLI → Visual Studio → Managed Identity 等从而让同一段代码在本地开发、CI/CD 与 Azure 云环境之间无缝切换这正是技能文档强调“永远不要在生产环境硬编码密码”的原因。ResourceIdentifierARM 中所有资源都有全局唯一的 ARM ID形如/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Sql/servers/{name}。SDK 通过ResourceIdentifier解析这些 ID 并在资源之间导航。权限模型操作 SQL 资源需要订阅/资源组级别的 ARM 权限如 Contributor 或自定义 RBAC 角色这与数据平面的数据库用户权限login/user 体系是完全独立的两套授权。资源层级从 ArmClient 向下导航ARM SDK 的核心设计是层级化集合模型——每一层资源都通过其父资源的Get{Child}s()方法即集合访问。技能文档给出的层级如下ArmClient └── SubscriptionResource └── ResourceGroupResource └── SqlServerResource ├── SqlDatabaseResource ├── ElasticPoolResource │ └── ElasticPoolDatabaseResource ├── SqlFirewallRuleResource ├── FailoverGroupResource ├── ServerBlobAuditingPolicyResource ├── EncryptionProtectorResource └── VirtualNetworkRuleResource理解这条链的意义在于集合*Collection负责 CRUD资源*Resource负责实例操作与再向下导航。例如要创建一个数据库必须先拿到SqlServerResource再通过server.GetSqlDatabases()获得SqlDatabaseCollection执行CreateOrUpdateAsync。这种“先定位父资源、再操作子资源”的模式贯穿整个 SDK与 azure-resource-manager-cosmosdb-dotnet 等同系列管理平面技能一致学习成本可以横向复用。核心工作流七个典型操作全解析以下代码均来自技能文档并补充了参数含义、取值范围与运行前提可直接作为脚本骨架。1. 创建 SQL Serverusing System; using Azure.ResourceManager.Sql; using Azure.ResourceManager.Sql.Models; // Get resource group var resourceGroup await subscription .GetResourceGroupAsync(my-resource-group); // Define server var serverData new SqlServerData(AzureLocation.EastUS) { AdministratorLogin sqladmin, AdministratorLoginPassword Environment.GetEnvironmentVariable(SQL_ADMIN_PASSWORD) ?? throw new InvalidOperationException(SQL_ADMIN_PASSWORD is required), Version 12.0, MinimalTlsVersion SqlMinimalTlsVersion.Tls1_2, PublicNetworkAccess ServerNetworkAccessFlag.Enabled }; // Create server (long-running operation) var serverCollection resourceGroup.Value.GetSqlServers(); var operation await serverCollection.CreateOrUpdateAsync( WaitUntil.Completed, my-sql-server, serverData); SqlServerResource server operation.Value;前提my-resource-group必须已存在若不存在可先用resourceGroupCollection.CreateOrUpdateAsync创建资源组。AdministratorLoginPassword建议从环境变量或密钥库如 Azure Key Vault读取文档代码用?? throw强制要求该变量存在避免空密码下发。Version 12.0当前 Azure SQL 逻辑服务器的引擎版本。MinimalTlsVersion SqlMinimalTlsVersion.Tls1_2强制最低 TLS 1.2满足安全基线要求。PublicNetworkAccess控制是否允许公网访问生产环境若需完全私网化可设为Disabled并配合VirtualNetworkRuleResource使用。长时运行操作LROCreateOrUpdateAsync返回一个ArmOperationWaitUntil.Completed表示阻塞等待操作完成WaitUntil.Started则立即返回、由调用方手动轮询或并行执行。2. 创建 SQL 数据库var databaseData new SqlDatabaseData(AzureLocation.EastUS) { Sku new SqlSku(S0) { Tier Standard }, MaxSizeBytes 2L * 1024 * 1024 * 1024, // 2 GB Collation SQL_Latin1_General_CP1_CI_AS, RequestedBackupStorageRedundancy SqlBackupStorageRedundancy.Local }; var databaseCollection server.GetSqlDatabases(); var dbOperation await databaseCollection.CreateOrUpdateAsync( WaitUntil.Completed, my-database, databaseData); SqlDatabaseResource database dbOperation.Value;Sku与Tier决定数据库的性能层与计费模型见下文 SKU 参考表。S0属于按 DTU 计费的 Standard 层若采用 vCore 模型则使用GP_Gen5_2这类 SKU。MaxSizeBytes数据库最大容量单位为字节2L * 1024 * 1024 * 1024即 2 GB。注意 Basic/Standard 层的容量上限受 SKU 约束。Collation默认SQL_Latin1_General_CP1_CI_AS不区分大小写创建后不可修改务必提前规划。RequestedBackupStorageRedundancy备份存储冗余策略Local/Zone/Geo影响可用性与成本。3. 创建弹性池var poolData new ElasticPoolData(AzureLocation.EastUS) { Sku new SqlSku(StandardPool) { Tier Standard, Capacity 100 // 100 eDTUs }, PerDatabaseSettings new ElasticPoolPerDatabaseSettings { MinCapacity 0, MaxCapacity 100 } }; var poolCollection server.GetElasticPools(); var poolOperation await poolCollection.CreateOrUpdateAsync( WaitUntil.Completed, my-elastic-pool, poolData); ElasticPoolResource pool poolOperation.Value;Capacity池的总容量Standard 层单位为 eDTU弹性 DTU此处 100 表示池共享 100 eDTU。PerDatabaseSettings单库在池内可占用的容量区间MinCapacity–MaxCapacity让池内数据库弹性伸缩而无需独立预配资源。若省略SDK 会使用默认的最小/最大设置。4. 将数据库加入弹性池var databaseData new SqlDatabaseData(AzureLocation.EastUS) { ElasticPoolId pool.Id }; await databaseCollection.CreateOrUpdateAsync( WaitUntil.Completed, pooled-database, databaseData);将ElasticPoolId指向已有池即可把数据库移入池内这是弹性池成本优化的核心用法——多个低负载数据库共享一份池容量避免各自按独立 SKU 计费。同样地将该字段置为null即可把数据库移出池。5. 配置防火墙规则// Allow Azure services var azureServicesRule new SqlFirewallRuleData { StartIPAddress 0.0.0.0, EndIPAddress 0.0.0.0 }; var firewallCollection server.GetSqlFirewallRules(); await firewallCollection.CreateOrUpdateAsync( WaitUntil.Completed, AllowAzureServices, azureServicesRule); // Allow specific IP range var clientRule new SqlFirewallRuleData { StartIPAddress 203.0.113.0, EndIPAddress 203.0.113.255 }; await firewallCollection.CreateOrUpdateAsync( WaitUntil.Completed, AllowClientIPs, clientRule);0.0.0.0–0.0.0.0是特殊规则表示“允许所有 Azure 服务访问”并非真正开放全公网通常在数据平面无法连通时作为排查第一步。客户端规则应遵循最小权限原则仅放行实际出口 IP 区间示例使用文档段203.0.113.0/24仅作演示请替换为真实 IP。技能文档特别提示在尝试建立任何连接之前先配置好防火墙规则否则数据平面连接会因 IP 未放行而被拒绝。6. 枚举资源// List all servers in subscription await foreach (var srv in subscription.GetSqlServersAsync()) { Console.WriteLine($Server: {srv.Data.Name} in {srv.Data.Location}); } // List databases in a server await foreach (var db in server.GetSqlDatabases()) { Console.WriteLine($Database: {db.Data.Name}, SKU: {db.Data.Sku?.Name}); } // List elastic pools await foreach (var ep in server.GetElasticPools()) { Console.WriteLine($Pool: {ep.Data.Name}, DTU: {ep.Data.Sku?.Capacity}); }GetSqlServersAsync()是订阅级别的便捷方法跨资源组枚举而server.GetSqlDatabases()/server.GetElasticPools()是服务器级别枚举。所有枚举方法都支持await foreach异步流式遍历返回的资源对象通过.Data暴露属性如Name、Location、Sku。7. 生成连接字符串// Build connection string (server FQDN is predictable) var serverFqdn ${server.Data.Name}.database.windows.net; var connectionString $Servertcp:{serverFqdn},1433; $Initial Catalog{database.Data.Name}; Persist Security InfoFalse; $User ID{server.Data.AdministratorLogin}; Passwordyour-password; MultipleActiveResultSetsFalse; EncryptTrue; TrustServerCertificateFalse; Connection Timeout30;;逻辑服务器 FQDN 遵循{server-name}.database.windows.net的确定性规则因此可由资源名直接拼出。EncryptTrueTrustServerCertificateFalse是面向生产的安全组合强制 TLS 加密且不信任自签名证书与前面MinimalTlsVersion Tls1_2的设置形成闭环。User ID/Password为 SQL 登录凭据若改用 Microsoft Entra IDAzure AD认证可替换为AuthenticationActive Directory Default等项并使用Microsoft.Data.SqlClient的对应认证模式。关键类型参考技能文档整理的核心类型及其职责如下理解它们能显著降低上手成本TypePurposeArmClientEntry point for all ARM operationsSqlServerResourceRepresents an Azure SQL serverSqlServerCollectionCollection for server CRUDSqlDatabaseResourceRepresents a SQL databaseSqlDatabaseCollectionCollection for database CRUDElasticPoolResourceRepresents an elastic poolElasticPoolCollectionCollection for elastic pool CRUDSqlFirewallRuleResourceRepresents a firewall ruleSqlFirewallRuleCollectionCollection for firewall rule CRUDSqlServerDataServer creation/update payloadSqlDatabaseDataDatabase creation/update payloadElasticPoolDataElastic pool creation/update payloadSqlFirewallRuleDataFirewall rule creation/update payloadSqlSkuSKU configuration (tier, capacity)命名规律{资源}Resource实例、{资源}Collection集合、{资源}Data创建/更新负载三件套构成了该 SDK 几乎全部资源类型的统一模式掌握此规律即可举一反三地使用FailoverGroupResource、ServerBlobAuditingPolicyResource、EncryptionProtectorResource、VirtualNetworkRuleResource等其余类型。SKU 选型参考数据库 SKUSKU NameTierDescriptionBasicBasic5 DTUs, 2 GB maxS0–S12Standard10-3000 DTUsP1–P15Premium125-4000 DTUsGP_Gen5_2GeneralPurposevCore-based, 2 vCoresBC_Gen5_2BusinessCriticalvCore-based, 2 vCoresHS_Gen5_2HyperscalevCore-based, 2 vCores弹性池 SKUSKU NameTierDescriptionBasicPoolBasic50-1600 eDTUsStandardPoolStandard50-3000 eDTUsPremiumPoolPremium125-4000 eDTUsGP_Gen5_2GeneralPurposevCore-basedBC_Gen5_2BusinessCriticalvCore-based选型要点DTU 模型Basic/Standard/Premium及*Pool计费简单适合中小型工作负载S0 起步 10 DTUPremium 最高 4000 DTU。vCore 模型GP_Gen5_2/BC_Gen5_2/HS_Gen5_2按核数与内存计费支持预留实例折扣Gen5表示硬件代次、_2表示 2 个 vCore。HyperscaleHS_面向超大数据库与高并发读取场景。弹性池以 eDTU弹性 DTU为单位PerDatabaseSettings决定池内单库容量区间。实际选型应以工作负载基准测试与成本测算为准而非仅凭 SKU 名称。最佳实践清单技能文档给出的八条实践原则对应到本文各环节如下WaitUntil.Completed必须在操作真正完成后再继续执行的场景如创建服务器后再创建数据库用它阻塞等待。WaitUntil.Started需要手动轮询或并行执行多个创建任务时使用避免串行等待拖慢整体编排。始终使用DefaultAzureCredential生产环境绝不硬编码密码本地用 IDE/CLI 凭据云端用托管身份CI 用服务主体。处理RequestFailedExceptionARM API 的绝大多数错误都以该异常抛出必须显式捕获见下文。使用CreateOrUpdateAsync实现幂等同一资源重复调用不会报“已存在”而是执行更新语义天然适合重试与状态收敛。通过Get*方法导航层级不要手工拼接子资源 ID统一用server.GetSqlDatabases()这类方法获取集合保证路径正确。多数据库用弹性池降本低利用率的多数据库共享池容量是明显的成本优化手段。先配防火墙再连数据平面避免连接超时排查时误判问题根因。错误处理读懂 ARM 异常using Azure; try { var operation await serverCollection.CreateOrUpdateAsync( WaitUntil.Completed, serverName, serverData); } catch (RequestFailedException ex) when (ex.Status 409) { Console.WriteLine(Server already exists); } catch (RequestFailedException ex) when (ex.Status 400) { Console.WriteLine($Invalid request: {ex.Message}); } catch (RequestFailedException ex) { Console.WriteLine($ARM Error: {ex.Status} - {ex.ErrorCode}: {ex.Message}); }ex.StatusHTTP 状态码是快速定位问题的第一线索400Bad Request请求参数非法如 SKU 与层级不匹配、容量超出配额404Not Found目标资源/资源组不存在409Conflict资源已存在结合CreateOrUpdateAsync的幂等语义通常可忽略或记录后继续403ForbiddenRBAC 权限不足需检查服务主体/身份的角色分配。ex.ErrorCodeARM 返回的机器可读错误码可用于程序化分支或写入监控告警。配合WaitUntil.Started的轮询场景还应关注轮询过程中的中间状态并对超时做兜底处理。相关 SDK 与延伸阅读SDKPurposeInstallMicrosoft.Data.SqlClientData plane (execute queries, stored procedures)dotnet add package Microsoft.Data.SqlClientAzure.ResourceManager.SqlManagement plane (this SDK)dotnet add package Azure.ResourceManager.SqlMicrosoft.EntityFrameworkCore.SqlServerORM for SQL Serverdotnet add package Microsoft.EntityFrameworkCore.SqlServer典型组合管理平面 SDK 完成“建库建表空间”等资源编排 → 数据平面 SDK 执行初始化 DDL/DML → ORMEF Core承载业务数据访问。三者职责互补构成完整的 Azure SQL .NET 技术栈。技能文档还规划了配套的参考文件目录references/server-management.md、references/database-operations.md、references/elastic-pools.md分别深入覆盖服务器 CRUD 与管理员凭据/Azure AD 认证/网络、数据库 CRUD 与扩容/备份/还原/复制、弹性池管理与扩缩容等进阶主题本技能当前版本暂未附带这些文件需要进阶场景时可结合 Azure 官方文档与仓库中同系列技能如 azure-sql、azure-resource-manager-cosmosdb-dotnet交叉参考。使用边界与注意事项适用场景本技能面向明确的 Azure SQL 资源管理平面编排任务创建/更新/查询服务器、数据库、弹性池、防火墙、故障转移组等当任务与上述范围匹配时使用。不可替代验证脚本产出不能替代针对具体环境的验证、测试与专家评审——尤其是网络策略、RBAC 权限与成本估算必须结合目标订阅实际情况确认。信息不足时及时澄清当缺少必要的输入参数如订阅 ID、资源组名、SQL 管理员密码、权限、安全边界或成功标准时应停止执行并向用户确认避免在错误假设下产生破坏性变更。本文所有代码与结论均以仓库中 azure-resource-manager-sql-dotnet 技能文档plugins/agentic-awesome-skills-claude/skills/azure-resource-manager-sql-dotnet/SKILL.md与之内容一致为事实基础示例中的占位值IP、密码、资源名需按实际环境替换后方可运行。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
