Windows-classic-samples 之 Hyper-V 虚拟光纤通道(FibreChannel)WMI 示例实战解析
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 编程有一定经验要求。
构建非常简单:
- 启动 Visual Studio,选择 File > Open > Project/Solution;
- 打开示例目录下的
FibreChannel.sln解决方案文件(位于 Samples/Hyper-V/FibreChannel/cs/); - 按 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 展示了完整调用链:
- 将用户输入的每个
WWPN/WWNN对交给 GetHostResourceFromWwn,先在Msvm_FcEndpoint中按SystemCreationClassName = 'Msvm_VirtualFcSwitch'、WWNN、WWPN查询对应的端点,再反查Msvm_VirtualFcSwitch实例路径——该路径即虚拟 SAN 的HostResource; - 通过 GetSettingsForPool 生成
Msvm_ResourcePoolSettingData嵌入实例,设置ResourceType(FC 连接资源类型64764,即 0xFCFC)、ResourceSubType(Microsoft:Hyper-V:FibreChannel Connection)、PoolId(即 SAN 名称)、Notes与ElementName; - 通过 GetNewPoolAllocationSettings 生成
Msvm_ResourceAllocationSettingData嵌入实例,填入PoolId与HostResource数组; - 取得单例服务 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:
- 添加合成 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; - 建立与 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:
- 遍历虚拟机的
Msvm_SyntheticFcPortSettingData关联集合,将VirtualPortWWPN、VirtualPortWWNN、SecondaryWWPN、SecondaryWWNN四个字段与命令行参数逐一比对(不区分大小写),收集匹配的端口路径; - 若未匹配到任何端口,打印提示并返回;
- 否则在
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 目录:
- Program.cs:入口,命令行模式分派与用法输出;
- CreateSan.cs、DeleteSan.cs、ModifySanName.cs、ModifySanPorts.cs:SAN 生命周期四件套;
- CreateVirtualFcPort.cs、DeleteVirtualFcPort.cs:虚拟 FC 端口增删;
- ConfigureWwnGenerator.cs、EnumerateFcPorts.cs:WWN 生成器配置与端口枚举;
- FibreChannelUtilities.cs:FC 领域专用工具(WWN→虚拟交换机路径、池设置构造、资源池查询);
- WmiUtilities.cs:通用 WMI 工具(服务获取、异步 Job 校验、错误解析);
- FibreChannel.csproj 与 FibreChannel.sln:工程与解决方案文件。
小结
通过本示例,你可以用 8 条命令行覆盖虚拟光纤通道管理的完整闭环:先 CreateSan 建立存储资源池,ModifySanPorts 调整其宿主端口,ModifySanName 重命名;再以 CreateVirtualFcPort 把关机状态的虚拟机接入 SAN,DeleteVirtualFcPort 断开连接;ConfigureWwnGenerator 控制自动 WWN 的分配范围;最后用 EnumerateFcPorts 校验整体状态。理解其背后的 Msvm_ResourcePoolConfigurationService 与 Msvm_VirtualSystemManagementService 双服务协作模型,以及 4096 异步 Job 的处理范式,即可在此基础上扩展出自己的 Hyper-V 存储管理自动化脚本。