Windows-classic-samples 之 Hyper-V 虚拟光纤通道(FibreChannel)WMI 示例实战解析

原创2026-10-14 18:27:321,873 阅读
文章标签:示例工程

Windows-classic-samples 之 Hyper-V 虚拟光纤通道(FibreChannel)WMI 示例实战解析

本指南围绕 Windows-classic-samples 仓库中的 Hyper-V FibreChannel 示例展开,系统讲解如何通过 Hyper-V WMI(V2)接口创建/删除/修改虚拟 SAN(存储区域网络)、为虚拟机增删虚拟光纤通道端口,以及配置 WWN(World Wide Name)生成器。读完本文,你将掌握一套可复制的命令行操作流程与底层 WMI 调用链,能够直接在自己的 Windows 8 / Windows Server 2012 及以上环境中管理虚拟光纤通道基础设施。

示例概览:用 WMI 管理虚拟 FC 基础设施

Hyper-V 的虚拟光纤通道功能允许宿主机上的虚拟机通过虚拟 HBA(主机总线适配器)直连物理光纤通道存储网络。本示例正是围绕这一能力的完整演示:它以 C# 编写,依赖 System.Management 命名空间访问 WMI,将所有操作封装为 8 种命令行模式,覆盖了从"创建 SAN"到"把虚拟机接入 SAN"的完整生命周期。

按官方说明,示例所演示的核心 WMI 方法包括:

操作 底层 WMI 方法 说明
创建虚拟 SAN Msvm_ResourcePoolConfigurationService.CreatePool 创建资源池并分配主机资源
删除虚拟 SAN Msvm_ResourcePoolConfigurationService.DeletePool 删除指定虚拟 SAN
修改虚拟 SAN 设置 Msvm_ResourcePoolConfigurationService.ModifyPoolSettings 修改 SAN 名称等设置
修改虚拟 SAN 资源 Msvm_ResourcePoolConfigurationService.ModifyPoolResources 增删 SAN 关联的主机 FC 端口
为 VM 创建虚拟 FC 端口 Msvm_VirtualSystemManagementService.AddResourceSettings 添加虚拟 HBA 并接入 SAN
从 VM 删除虚拟 FC 端口 Msvm_VirtualSystemManagementService.RemoveResourceSettings 移除指定 WWN 对应的虚拟端口
配置 WWN 生成器 Msvm_VirtualSystemManagementService.ModifyServiceSettings 修改 MinimumWWPNAddress、MaximumWWPNAddress、CurrentWWNNAddress
枚举虚拟 FC 端口 查询 Msvm_FcPortAllocationSettingData 与 Msvm_ExternalFcPort 类 列出外部 FC 端口及其状态

从源码结构看,8 种模式分别由独立的 CreateSan.cs、DeleteSan.cs、ModifySanName.cs、ModifySanPorts.cs、CreateVirtualFcPort.cs、DeleteVirtualFcPort.cs、ConfigureWwnGenerator.cs、EnumerateFcPorts.cs 实现,统一由 Program.cs 按第一个命令行参数分派,且匹配时不区分大小写。

环境要求与构建步骤

按 README 的说明,示例面向 Windows 8(Client)与 Windows Server 2012(Server)及以上环境,涉及的管理特性自 Windows 8.1 / Windows Server 2012 R2 起可用。示例本身对 WMI 编程有一定经验要求。

构建非常简单:

  1. 启动 Visual Studio,选择 File > Open > Project/Solution;
  2. 打开示例目录下的 FibreChannel.sln 解决方案文件(位于 Samples/Hyper-V/FibreChannel/cs/);
  3. 按 F7(Visual Studio 2013 中为 F6),或通过 Build > Build Solution 完成编译。

工程文件 FibreChannel.csproj 显示:程序集名称为 FibreChannelSamples,目标框架为 .NET Framework 4.0,输出类型为控制台可执行程序(Exe),仅引用 System、System.Management 与 System.XML 三个程序集,无需任何外部 NuGet 依赖。

运行方式与帮助信息

必须注意:本示例必须以管理员身份运行,因为其 WMI 操作涉及宿主机层面的资源池配置。

在 Visual Studio 中按 F5(Debug > Start Debugging)可进入调试运行,按 Ctrl+F5(Debug > Start Without Debugging)直接运行;也可以在编译产物 FibreChannelSamples.exe 所在的目录中手动执行。

不带任何参数或带未知模式名时,程序会输出完整用法清单(实现见 Program.cs):

FibreChannelSamples.exe <SampleName> <Arguments>

Supported SampleNames:
   CreateSan <SanName> <[WWPN WWNN]+> [SAN Notes]
   DeleteSan <SanName>
   ModifySanName <SanName> <NewSanName>
   ModifySanPorts <SanName> [WWPN WWNN]*
   CreateVirtualFcPort <VmName> <SanName> [WWPN-A WWNN-A WWPN-B WWNN-B]
   DeleteVirtualFcPort <VmName> <WWPN-A WWNN-A WWPN-B WWNN-B>
   ConfigureWwnGenerator <Min WWPN> <Max WWPN> [New WWNN]
   EnumerateFcPorts

运行 FibreChannelSamples.exe /? 可快速获得同样的操作列表。每种模式的 ExecuteSample 入口还会在参数不足或首参为 /? 时单独打印自己的用法行,方便单模式调试。

创建虚拟 SAN(CreateSan)

虚拟 SAN 在 WMI 模型中对应一个 FC 连接资源池。命令格式:

FibreChannelSamples.exe CreateSan <SanName> <[WWPN WWNN]+> [SAN Notes]

参数说明:

  • SanName:要创建的虚拟 SAN 名称;
  • WWPN / WWNN 对:SAN 的主机端口名(WWPN)与节点名(WWNN),每对两个参数,可连续提供多对;WWN 为 16 位十六进制字符串(例如 1122334455667788);
  • SAN Notes:SAN 备注,须用引号包裹,可选;省略时程序会自动生成默认备注 Notes for virtual SAN - <SanName>。

完整调用示例(摘自 Program.cs):

FibreChannelSamples.exe CreateSan TestSAN 1122334455667788 0011223344556677 "Notes for TestSAN"
FibreChannelSamples.exe CreateSan TestSAN 1122334455667788 0011223344556677 2233445566778899 0011223344556677

底层实现

CreateSan.cs 展示了完整调用链:

  1. 将用户输入的每个 WWPN/WWNN 对交给 GetHostResourceFromWwn,先在 Msvm_FcEndpoint 中按 SystemCreationClassName = 'Msvm_VirtualFcSwitch'、WWNN、WWPN 查询对应的端点,再反查 Msvm_VirtualFcSwitch 实例路径——该路径即虚拟 SAN 的 HostResource;
  2. 通过 GetSettingsForPool 生成 Msvm_ResourcePoolSettingData 嵌入实例,设置 ResourceType(FC 连接资源类型 64764,即 0xFCFC)、ResourceSubType(Microsoft:Hyper-V:FibreChannel Connection)、PoolId(即 SAN 名称)、Notes 与 ElementName;
  3. 通过 GetNewPoolAllocationSettings 生成 Msvm_ResourceAllocationSettingData 嵌入实例,填入 PoolId 与 HostResource 数组;
  4. 取得单例服务 Msvm_ResourcePoolConfigurationService,调用其 CreatePool 方法,并指定父池为 primordial 池(Primordial = TRUE,见 GetResourcePoolPath)。

代码注释特别指出:FC 连接资源池只有唯一一个父池,即 primordial 池,因此 ParentPools 数组固定为长度 1。

删除虚拟 SAN(DeleteSan)

命令格式:

FibreChannelSamples.exe DeleteSan <SanName>

其中 SanName 为要删除的 SAN 名称。实现位于 DeleteSan.cs:先通过 GetResourcePoolPath(scope, poolId) 定位该 SAN 对应的 Msvm_ResourcePool 实例路径,再在 Msvm_ResourcePoolConfigurationService 上调用 DeletePool 方法,Pool 参数即该实例路径。

修改虚拟 SAN 设置(ModifySanName)

命令格式:

FibreChannelSamples.exe ModifySanName <SanName> <NewSanName>

参数含义:SanName 为 SAN 当前名称,NewSanName 为要改成的名称。实现位于 ModifySanName.cs:程序用新名称重新生成一份 Msvm_ResourcePoolSettingData,然后调用 Msvm_ResourcePoolConfigurationService.ModifyPoolSettings,传入 ChildPool(当前池路径)与 PoolSettings(新设置),实现重命名。

修改虚拟 SAN 的资源(ModifySanPorts)

命令格式:

FibreChannelSamples.exe ModifySanPorts <SanName> <[WWPN WWNN]+>

参数含义:

  • SanName:要修改的 SAN 名称;
  • WWPN / WWNN 对:SAN 的新端口名与节点名,可提供多对;注意:该参数列表在语法上是可选的——当只提供 SanName 而不带任何 WWN 对时,程序会移除 SAN 上此前分配的全部主机资源(即清空 SAN)。

实现位于 ModifySanPorts.cs:程序将新 WWN 对转换为 HostResource 路径后,调用 Msvm_ResourcePoolConfigurationService.ModifyPoolResources,参数包括 ChildPool(目标池路径)、ParentPools(primordial 池)与 AllocationSettings(新的 Msvm_ResourceAllocationSettingData 嵌入实例)。当 newHostResources 为空时,HostResource 为空数组,效果即删除全部已分配资源。

对应示例(摘自 Program.cs):

FibreChannelSamples.exe ModifySanPorts TestSAN 2233445566778899 0011223344556677
FibreChannelSamples.exe ModifySanPorts TestSAN

为虚拟机创建虚拟 FC 端口(CreateVirtualFcPort)

命令格式:

FibreChannelSamples.exe CreateVirtualFcPort <VmName> <SanName> [WWPN-A WWNN-A WWPN-B WWNN-B]

参数含义:

  • VmName:要添加虚拟 FC 端口的虚拟机名称;
  • SanName:要接入的虚拟 SAN 名称;
  • WWPN-A / WWNN-A / WWPN-B / WWNN-B:虚拟 FC 端口的主端口与备用端口的 WWN,可选;省略时由 WWN 生成器自动生成(WWNN 取当前 CurrentWWNNAddress)。

示例(摘自 Program.cs):

FibreChannelSamples.exe CreateVirtualFcPort TestVM TestSAN
FibreChannelSamples.exe CreateVirtualFcPort TestVM TestSAN 33445566778899aa 0033445566778899 33445566778899bb 0033445566778899

前提条件与限制

源码注释明确给出两条硬性限制:

  • 虚拟机必须处于关机(power off)状态才能添加 FC 适配器设备(见 CreateVirtualFcPort.cs);
  • 每台虚拟机最多配置 4 个 FC 适配器设备。

底层实现

该模式是最复杂的,CreateVirtualFcPort.cs 分两步调用 Msvm_VirtualSystemManagementService.AddResourceSettings:

  1. 添加合成 FC 适配器:通过查询 Msvm_ResourcePool(ResourceSubType = 'Microsoft:Hyper-V:Synthetic FibreChannel Port' AND Primordial = True)取得默认合成适配器设置对象(Msvm_SyntheticFcPortSettingData),写入 ElementName(Fibre Channel Adapter)、VirtualPortWWPN、VirtualPortWWNN、SecondaryWWPN、SecondaryWWNN 五个属性后,以 AffectedConfiguration(虚拟机设置对象路径)+ ResourceSettings 调用 AddResourceSettings;
  2. 建立与 SAN 的连接:通过 GetDefaultFcPortAllocationSettingData 按 ResourceType = 64764 AND PoolID = <SanName> 找到 SAN 的默认连接设置对象(Msvm_FcPortAllocationSettingData),将其 PoolID 设为 SAN 名称、Parent 设为刚创建的适配器路径,再次调用 AddResourceSettings,把虚拟端口"插"进 SAN。

WWN 自动生成逻辑见 FibreChannelUtilities.GenerateWorldWideNames:它读取 Msvm_VirtualSystemManagementServiceSettingData.CurrentWWNNAddress 作为两套 WWN 的节点名,然后调用 Msvm_VirtualSystemManagementService.GenerateWwpn 方法(NumberOfWwpns = 2)一次性生成两个 WWPN。

从虚拟机删除虚拟 FC 端口(DeleteVirtualFcPort)

命令格式:

FibreChannelSamples.exe DeleteVirtualFcPort <VmName> <WWPN-A> <WWNN-A> <WWPN-B> <WWNN-B>

参数含义:VmName 为目标虚拟机名称;WWPN-A / WWNN-A / WWPN-B / WWNN-B 为要删除的虚拟 FC 端口的四元组 WWN(主端口与备用端口的 WWPN/WWNN,顺序固定)。

实现位于 DeleteVirtualFcPort.cs:

  1. 遍历虚拟机的 Msvm_SyntheticFcPortSettingData 关联集合,将 VirtualPortWWPN、VirtualPortWWNN、SecondaryWWPN、SecondaryWWNN 四个字段与命令行参数逐一比对(不区分大小写),收集匹配的端口路径;
  2. 若未匹配到任何端口,打印提示并返回;
  3. 否则在 Msvm_VirtualSystemManagementService.RemoveResourceSettings 上以 ResourceSettings(端口路径数组)完成删除。同样地,此操作要求虚拟机处于关机状态。

配置 WWN 生成器(ConfigureWwnGenerator)

命令格式:

FibreChannelSamples.exe ConfigureWwnGenerator <Min WWPN> <Max WWPN> [New WWNN]

参数含义:

  • Min WWPN:WWN 生成器的 WWPN 下限,对应 Msvm_VirtualSystemManagementServiceSettingData.MinimumWWPNAddress;
  • Max WWPN:WWN 生成器的 WWPN 上限,对应 MaximumWWPNAddress;
  • New WWNN:新的 WWNN 值,对应 CurrentWWNNAddress,可选;省略时保持现有 WWNN 不变。

示例(摘自 Program.cs):

FibreChannelSamples.exe ConfigureWwnGenerator 1122334400000000 11223344FFFFFFFF
FibreChannelSamples.exe ConfigureWwnGenerator 1122334400000000 11223344FFFFFFFF 0011223344556677

实现位于 ConfigureWwnGenerator.cs:程序读取 Msvm_VirtualSystemManagementServiceSettingData 单例实例,修改上述三个属性后,通过 Msvm_VirtualSystemManagementService.ModifyServiceSettings 方法(SettingData 参数传入嵌入实例文本)提交配置。此配置将影响此后所有自动生成的 WWPN/WWNN——例如 CreateVirtualFcPort 省略 WWN 参数时的自动生成即落在该范围内。

枚举虚拟 FC 端口(EnumerateFcPorts)

命令格式:

FibreChannelSamples.exe EnumerateFcPorts

该模式不接受任何额外参数。实现位于 EnumerateFcPorts.cs,输出格式为三列:

WorldWideNodeName   WorldWidePortName   Status
-----------------   -----------------   ------

对每个 Msvm_ExternalFcPort 实例,输出其 WWNN、WWPN 属性;状态判定规则如下:

  • 若 IsHyperVCapable 属性为 false,状态显示为 Not Hyper-V Capable;
  • 若该端口的主机资源(Msvm_VirtualFcSwitch 路径)已归属某个虚拟 SAN(出现在该 SAN 的 Msvm_FcPortAllocationSettingData.HostResource 数组中),状态显示为对应的 SAN 名称;
  • 否则状态为 Available。

SAN 归属信息通过 BuildSanInfo 获取:枚举所有非 primordial 的 FC 连接资源池(Primordial = false),再经关联类读取 Msvm_FcPortAllocationSettingData 的 HostResource 数组。代码注释强调一个端口只能归属于一个虚拟 SAN。

底层 WMI 调用链与关键常量

整个示例统一通过命名空间 root\virtualization\v2 连接 Hyper-V WMI(见 GetFcScope)。三个核心服务类分工明确:

  • Msvm_ResourcePoolConfigurationService:单例类,负责 SAN(资源池)的 CreatePool、DeletePool、ModifyPoolSettings、ModifyPoolResources;
  • Msvm_VirtualSystemManagementService:负责虚拟设备层面的 AddResourceSettings、RemoveResourceSettings、GenerateWwpn、ModifyServiceSettings;
  • Msvm_VirtualSystemManagementServiceSettingData:保存 WWN 生成器的 MinimumWWPNAddress、MaximumWWPNAddress、CurrentWWNNAddress 等配置。

关键常量定义于 FibreChannelUtilities.cs:

常量 值 用途
FcConnectionResourceType 64764(0xFCFC) FC 连接资源池 / 连接设置对象的 ResourceType
FcConnectionResourceSubType Microsoft:Hyper-V:FibreChannel Connection 虚拟 SAN 连接资源子类型
FcDeviceName Fibre Channel Adapter 虚拟 HBA 的 ElementName

异步 Job 处理机制

Hyper-V WMI 的多数变更方法采用"方法立即返回,Job 异步执行"的模式。公共工具 WmiUtilities.ValidateOutput 对此做了统一封装:当方法返回值(ReturnValue)为 4096 时,说明启动了异步操作,程序会取出 Job 对象,每秒轮询其 JobState 直到完成(完成、完成但有警告、终止、异常、被终止均视为结束),失败时进一步调用 Job 的 GetErrorEx 方法解析并打印 Msvm_Error 明细(见 PrintMsvmErrors),最终按 throwIfFailed 决定是否抛出异常。所有示例在调用 WMI 方法后都调用 ValidateOutput(outParams, scope, true, true),因此任何失败都会以明确异常呈现在控制台。

源码文件地图

本示例的全部代码集中在 cs 目录:

小结

通过本示例,你可以用 8 条命令行覆盖虚拟光纤通道管理的完整闭环:先 CreateSan 建立存储资源池,ModifySanPorts 调整其宿主端口,ModifySanName 重命名;再以 CreateVirtualFcPort 把关机状态的虚拟机接入 SAN,DeleteVirtualFcPort 断开连接;ConfigureWwnGenerator 控制自动 WWN 的分配范围;最后用 EnumerateFcPorts 校验整体状态。理解其背后的 Msvm_ResourcePoolConfigurationService 与 Msvm_VirtualSystemManagementService 双服务协作模型,以及 4096 异步 Job 的处理范式,即可在此基础上扩展出自己的 Hyper-V 存储管理自动化脚本。

登录后查看全文
Windows-classic-samples