第02章：开发环境搭建、源码获取与编译

本章的目标是让你在自己的机器上完成两件事：

用 NuGet 包消费 Xbim，做应用层开发；
从源码编译 XbimEssentials 与 XbimGeometry 两个仓库，做核心二次开发或排查问题。

1. 操作系统与工具链概览

Xbim 不同模块对操作系统的要求不一致：

模块	平台支持	说明
Xbim.Common / Xbim.Ifc / Xbim.Ifc2x3 / Xbim.Ifc4 / Xbim.Ifc4x3	Windows / Linux / macOS（.NET Standard 2.0/2.1，.NET 6/8）	纯托管，跨平台无障碍
Xbim.IO.Esent	仅 Windows	依赖 Windows ESE / Esent 引擎
Xbim.IO.Memory	跨平台	.NET Core/Linux 上推荐使用
Xbim.Geometry.Engine（C++/CLI）	Windows x64（强烈推荐）	通过 C++/CLI 桥接 OCCT 7.6.3，本质上是 Windows 原生 DLL
Xbim.Geometry.Engine.Interop	Windows	加载 native 引擎
Xbim.WindowsUI / XbimXplorer	Windows + WPF	.NET Framework 4.7.2+
Xbim.WebUI	浏览器，编译用 Node.js	跨平台

结论：

仅做 IFC 数据处理（读写、查询、编辑、属性、关系）：Windows / Linux / macOS 都可以，推荐用 .NET 6 或 .NET 8 + VS Code / Rider。
涉及几何转换、网格生成、布尔运算、Wexbim 输出、桌面查看器：强烈建议使用 Windows + Visual Studio 2022，几何引擎仅在 Windows 上稳定可用。

2. 必备软件清单

2.1 公共组件（所有平台）

.NET SDK：6.0 LTS 或 8.0 LTS（推荐 8.0）；下载：https://dotnet.microsoft.com/download。
Git：用于克隆仓库；下载：https://git-scm.com/。
IDE：任选其一
- Visual Studio 2022 Community / Professional（Windows）
- JetBrains Rider（Windows / Linux / macOS）
- Visual Studio Code + C# Dev Kit
NuGet CLI（可选）：现代 .NET SDK 已内置 dotnet add package。

2.2 编译 XbimGeometry 的额外组件（Windows）

XbimGeometry 仓库在 README 中明确给出编译要求：

Visual Studio 2019 or 2022 is recommended. … Visual C++ Core desktop features, MSVC v142 - VS 2019 C++ build tools, Windows 10+ SDK (minimum 10.0.108362.0).

也就是说，要从源码编译几何引擎，需要 Visual Studio Installer 中安装：

“.NET 桌面开发” 工作负载；
“使用 C++ 的桌面开发” 工作负载；
MSVC v142 - VS 2019 C++ 生成工具（XbimGeometry 当前以 v142 工具链为目标，VS2022 也兼容）；
Windows 10/11 SDK（≥ 10.0.18362.0）；
C++/CLI 支持（v142 的 C++/CLI 支持组件） —— 这是连接 OCCT C++ 与 .NET 的关键。

2.3 编译 Xbim.WebUI 的额外组件

Node.js 16+；
npm 或 pnpm；
TypeScript 编译器（仓库已配置）。

3. 通过 NuGet 消费 Xbim（最常见的方式）

如果你只是想用 Xbim 做应用开发，完全不需要克隆源码。NuGet 是 Xbim 的官方分发渠道。

3.1 创建一个最小项目

mkdir HelloXbim
cd HelloXbim
dotnet new console -f net8.0
dotnet add package Xbim.Essentials

如果需要几何与可视化：

dotnet add package Xbim.Geometry --version 5.1.*

注意：Xbim.Geometry 包内会带 native DLL（仅 Windows 可加载）。在 Linux/macOS 上引用此包不会报错，但运行时调用几何 API 会抛出 BadImageFormatException 之类的异常。

3.2 主要 NuGet 包列表

包名	作用
`Xbim.Essentials`	元包，引入 Common + 各 IFC 模式 + IO + Tessellator
`Xbim.Common`	通用基础设施，被其他包依赖
`Xbim.Ifc2x3` / `Xbim.Ifc4` / `Xbim.Ifc4x3`	单独的 schema 实体类库
`Xbim.IO.Esent`	Esent 数据库后端（Windows）
`Xbim.IO.MemoryModel`	内存模型后端
`Xbim.Geometry`	几何引擎元包，含 native DLL
`Xbim.WindowsUI`	WPF 桌面控件、XbimXplorer 部分
`Xbim.CobieExpress` / `Xbim.IO.CobieExpress`	COBie 实现
`Xbim.IDS.Validator`	IDS 校验器

3.3 预览版（develop 分支）

xBIM 团队会把 develop 分支构建产物发布到 MyGet。要使用这些预览版，在解决方案根目录添加 nuget.config：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
    <add key="xbim-develop" value="https://www.myget.org/F/xbim-develop/api/v3/index.json" />
    <add key="xbim-master"  value="https://www.myget.org/F/xbim-master/api/v3/index.json" />
  </packageSources>
</configuration>

随后 dotnet add package Xbim.Essentials --version 6.0.*-* 就可以拉取预发布版本。

4. 从源码编译 XbimEssentials

XbimEssentials 是纯托管解决方案，跨平台编译毫无障碍。

4.1 克隆仓库

git clone https://github.com/xBimTeam/XbimEssentials.git
cd XbimEssentials

仓库默认分支为 master（稳定版）。日常开发请切到 develop：

git checkout develop

4.2 仓库结构速览

XbimEssentials/
├── Xbim.Common/                # 通用基础设施
├── Xbim.Tessellator/           # 几何细分器
├── Xbim.Ifc/                   # IfcStore 等高层 API
├── Xbim.Ifc2x3/                # IFC2x3 实体类（自动生成）
├── Xbim.Ifc4/                  # IFC4 实体类（自动生成）
├── Xbim.Ifc4x3/                # IFC4x3 实体类（自动生成）
├── Xbim.IO.Esent/              # Esent 数据库后端
├── Xbim.IO.MemoryModel/        # 内存后端
├── Xbim.IO/                    # 通用 IO 抽象
├── Xbim.IO.Step21/             # STEP21 解析器/写入器
├── Xbim.IO.Xml/                # ifcXML 读写
├── Xbim.CodeGeneration/        # 从 EXPRESS schema 生成 C# 类
├── Tests/                      # 各类单元测试
├── XbimEssentials.sln          # 主解决方案
└── ...

4.3 编译

dotnet restore XbimEssentials.sln
dotnet build XbimEssentials.sln -c Release
dotnet test  XbimEssentials.sln -c Release --no-build

在 Linux/macOS 上编译时，部分依赖 Windows 特性的项目（如 Esent）会被自动跳过或显示警告。

4.4 调试 Xbim.CodeGeneration

Xbim.CodeGeneration 是 Xbim 的”秘密武器”——所有 IFC 实体类都不是手工编写的，而是从 BuildingSMART 提供的 .exp（EXPRESS schema）文件自动生成。它解决了一个非常现实的问题：IFC 实体动辄数百个，每次 Schema 升级（IFC2x3 → IFC4 → IFC4x3）都涉及代码大改。Xbim 通过：

解析 EXPRESS schema 得到抽象语法树；
应用代码生成模板（T4-like）；
输出强类型 C# 类、接口、属性、序列化代码。

如果你打算扩展 IFC4x3 支持新模块，或加入私有 schema 字段，理解这个项目至关重要。第 04 章会更深入地分析它。

5. 从源码编译 XbimGeometry

这是难度最大的一步，也是新手最容易卡住的地方。

5.1 克隆

git clone https://github.com/xBimTeam/XbimGeometry.git
cd XbimGeometry
git checkout develop

5.2 仓库结构速览

XbimGeometry/
├── Xbim.Geometry.Engine/                   # C++/CLI 工程，包装 OCCT
├── Xbim.Geometry.Engine.Interop/           # 托管侧 Interop 与 native 加载器
├── Xbim.Geometry.Abstractions/             # 几何接口（与 OCCT 解耦的 API）
├── Xbim.ModelGeometry.Scene/               # 场景管理、Wexbim 输出
├── Xbim.Geometry.Engine.Tests/             # 单元测试（含 IFC 几何回归用例）
├── Xbim.Geometry.NetCore/                  # .NET Core 版几何接口
├── Tools/, ThirdParty/                     # 第三方依赖（含 OCCT 头/库）
└── XbimGeometry.sln

5.3 OCCT 依赖

XbimGeometry 当前捆绑 OCCT 7.6.3 的预编译库（位于 ThirdParty/ 或通过 NuGet 拉取 Xbim.Geometry.Engine.OCC），以避免开发者从零编译数小时的 OCCT。这意味着多数情况下你不需要自己编译 OCCT，但需要：

系统是 Windows x64；
Visual Studio 选了 C++ 桌面开发 与 C++/CLI；
Windows SDK 安装到位。

5.4 编译流程（Visual Studio 2022）

用 VS2022 打开 XbimGeometry.sln；
设置解决方案配置：Release + x64；
右键解决方案 → 还原 NuGet 包；
生成解决方案。

如果一切顺利，输出目录会出现：

Xbim.Geometry.Engine.dll（Mixed-mode，C++/CLI 主体）
一组 OCCT 原生 DLL（TKernel.dll、TKMath.dll、TKBRep.dll、TKTopAlgo.dll 等）
Xbim.Geometry.Engine.Interop.dll、Xbim.ModelGeometry.Scene.dll 等

5.5 命令行编译

dotnet restore XbimGeometry.sln
msbuild XbimGeometry.sln /p:Configuration=Release /p:Platform=x64

注意：不能用 dotnet build 直接构建 C++/CLI 项目，必须用 MSBuild（VS Developer PowerShell 中可直接运行）。

5.6 常见问题

error MSB8020 / 平台工具集未找到：缺 v142 工具集，从 VS Installer 补装。
找不到 corecrt.h、windows.h：缺 Windows SDK，从 VS Installer 补装。
C++/CLI 项目无法加载：缺 “C++/CLI 支持” 组件。
运行时 BadImageFormatException：x86 / x64 不一致，确认应用程序也是 x64。

6. 运行 XbimXplorer 桌面查看器

XbimXplorer 是一个用 WPF 写的 IFC/Wexbim 浏览器，是 Xbim 学习中最有价值的工具：

直接打开 .ifc / .ifcXML / .ifcZIP 文件；
树状显示空间结构、构件、属性、量、材质；
支持几何渲染、视图剖切、拾取；
支持 STEP 文件直接编辑（高级）。

获取方式：

下载二进制：XbimWindowsUI Releases；
从源码构建：克隆 XbimWindowsUI 仓库，用 VS2022 打开 XbimWindowsUI.sln，设为启动项目运行即可。

7. 第一个示例工程

完成上述准备后，我们做一个最小可运行示例。新建项目：

dotnet new console -n FirstXbim -f net8.0
cd FirstXbim
dotnet add package Xbim.Essentials

Program.cs：

using Xbim.Common.Step21;
using Xbim.Ifc;
using Xbim.Ifc4.Interfaces;

if (args.Length == 0)
{
    Console.WriteLine("Usage: FirstXbim <ifc-file>");
    return;
}

var path = args[0];
using var model = IfcStore.Open(path);

Console.WriteLine($"Schema = {model.SchemaVersion}");

var project = model.Instances.OfType<IIfcProject>().First();
Console.WriteLine($"Project Name : {project.Name}");
Console.WriteLine($"Project GlobalId : {project.GlobalId}");

var summary = model.Instances
    .GroupBy(i => i.ExpressType.Name)
    .OrderByDescending(g => g.Count())
    .Take(10);

foreach (var g in summary)
    Console.WriteLine($"{g.Key,-40} {g.Count(),8}");

编译运行：

dotnet run -- "C:\path\to\SampleHouse.ifc"

如果输出了 schema 名（例如 Ifc4）、项目信息以及实体计数前 10，恭喜，你的开发环境已经搭好。

8. 测试数据从哪里来？

第一次接触 IFC 时，找一份”小而全”的测试模型至关重要。推荐：

buildingSMART Sample Files：https://github.com/buildingSMART/Sample-Test-Files
XbimSamples：https://github.com/xBimTeam/XbimSamples，仓库中有 SampleHouse.ifc、Wall_With_Window.ifc 等若干模型。
IfcOpenHouse：BlenderBIM 社区提供的可重现样例。
Karlsruhe IFC Demo Models：https://github.com/CDIC-IBA/IFC-DemoFiles。

9. 小结

至此，你已经具备：

一个可以正常 dotnet restore / build / test 的 .NET 开发环境；
（可选）一个能编译 C++/CLI 的 Visual Studio 2022 完整安装；
本地克隆并能成功编译 XbimEssentials 与 XbimGeometry；
一份带几个 .ifc 文件的测试集；
一个能跑通”打开 IFC、统计实体”的最小程序。

下一章我们将进入 IFC 标准本身，理解 Xbim 背后的数据模型。