第二章：开发环境搭建与项目配置

2.1 开发环境要求

2.1.1 硬件要求

配置项	最低要求	推荐配置
CPU	Intel Core i5 或同等性能	Intel Core i7/i9 或 AMD Ryzen 7/9
内存	8GB RAM	16GB RAM 或更高
硬盘	50GB 可用空间（推荐SSD）	100GB SSD
显卡	支持OpenGL 3.3的独立显卡	NVIDIA GTX 1060 或更高
显示器	1920×1080 分辨率	2560×1440 或更高

2.1.2 操作系统要求

• Windows 10 64位（版本1909或更高）
• Windows 11 64位

注意：虽然.NET 10支持跨平台，但LightCAD当前的UI层（WinForms + Avalonia）主要面向Windows。未来版本可能扩展到Linux和macOS。

2.1.3 软件要求

软件	版本要求	用途
Visual Studio 2026	17.14 或更高	主要开发IDE
.NET 10 SDK	最新版	编译和运行
Git	2.30+	版本控制
NuGet	内置于VS	包管理

2.2 安装Visual Studio 2026

2.2.1 下载安装

1. 访问 Visual Studio官网 下载Visual Studio 2026
2. 支持社区版（免费）、专业版或企业版
3. 运行安装程序

2.2.2 安装工作负载

在Visual Studio Installer中，必须选择以下工作负载：

必选工作负载：

• 「.NET桌面开发」：这是最核心的工作负载，包含WinForms和WPF开发所需的全部组件

推荐额外安装的组件：

• 「ASP.NET和Web开发」：用于SignalR通信相关的调试
• 「Visual Studio扩展开发」：如果您计划开发VS扩展来辅助LightCAD开发

2.2.3 单独组件选择

在"单独的组件"选项卡中，确保选择：

• .NET 10 Runtime
• .NET 10 SDK
• Windows 10 SDK（最新版本）
• NuGet包管理器
• 文本模板转换

2.3 安装.NET 10 SDK

2.3.1 通过VS安装

如果在安装VS时已选择.NET桌面开发工作负载，.NET 10 SDK通常会自动安装。

2.3.2 手动安装

如果需要手动安装：

1. 访问 .NET下载页面
2. 下载.NET 10 SDK（x64版本）
3. 运行安装程序
4. 验证安装：

dotnet --version
# 应该输出 8.0.x

dotnet --list-sdks
# 应该包含 8.0.xxx

2.4 获取LightCAD源代码

2.4.1 使用Git克隆

# 克隆主仓库
git clone https://github.com/znlgis/lightcad1.git

# 进入项目目录
cd lightcad1

2.4.2 使用Visual Studio克隆

1. 打开Visual Studio 2026
2. 在启动页面选择"克隆存储库"
3. 输入仓库URL：https://github.com/znlgis/lightcad1.git
4. 选择本地路径
5. 点击"克隆"

2.4.3 项目目录结构详解

lightcad1/
│
├── LightCAD1.sln                        # 主解决方案文件
│
├── src/                                  # 源代码目录
│   │
│   ├── LightCAD.MathLib/                # 数学库项目
│   │   ├── LightCAD.MathLib.csproj
│   │   ├── Basic/                       # 基础数学类型
│   │   ├── Curve/                       # 曲线数学
│   │   ├── Intersection/               # 交集计算
│   │   └── Utilities/                   # 工具函数
│   │
│   ├── LightCAD.Core/                   # 核心项目
│   │   ├── LightCAD.Core.csproj
│   │   ├── Elements/                    # 图元实体
│   │   │   ├── Basic/                   # 2D基本图元
│   │   │   ├── Element3d/              # 3D图元
│   │   │   ├── Solid/                   # 实体建模
│   │   │   ├── Dim/                     # 2D标注
│   │   │   ├── Dim3/                    # 3D标注
│   │   │   ├── Table/                   # 表格元素
│   │   │   ├── Mass/                    # 质量属性
│   │   │   ├── Misc/                    # 杂项元素
│   │   │   ├── Ref/                     # 引用元素
│   │   │   └── VoidElement/            # 空元素
│   │   └── ...
│   │
│   ├── LightCAD.RenderUtils/            # 渲染工具项目
│   │   ├── 3dcontrols/                  # 3D控件
│   │   ├── AssetManagers/              # 资源管理
│   │   ├── ThreeUtils/                  # Three.js工具
│   │   └── Events/                      # 事件系统
│   │
│   ├── LightCAD.Drawing/                # 绘图项目
│   │   ├── InputSys/                    # 输入系统
│   │   ├── Snap/                        # 捕捉系统
│   │   ├── PViewPort/                   # 视口组件
│   │   └── ViewPortRtAction/           # 视口运行时动作
│   │
│   ├── LightCAD.Runtime/                # 运行时项目
│   │   ├── ViewBuilder/                 # 视图构建器
│   │   │   ├── ViewBuilder.cs           # 核心构建器（71KB）
│   │   │   ├── ProjectioinProcessor.cs  # 投影处理器（39KB）
│   │   │   ├── PolygonExt.cs            # 多边形扩展
│   │   │   ├── BrepViewBuilder.cs       # B-Rep视图构建
│   │   │   └── GpuVisibleFilter.cs      # GPU可见性过滤
│   │   └── ...
│   │
│   ├── LightCAD.Model/                  # UI模型控件
│   │   ├── ModelControl.axaml           # 模型控件
│   │   ├── ModelEditor.axaml            # 模型编辑器
│   │   ├── ModelViewControl.axaml       # 模型视图控件
│   │   └── ModelStatusBar.axaml         # 状态栏
│   │
│   ├── LightCAD.WinForm/                # WinForm应用
│   │   ├── Program.cs                    # 程序入口
│   │   └── Font/                         # 字体资源
│   │       ├── TTF/                      # TrueType字体
│   │       └── Shx/                      # SHX CAD字体
│   │
│   ├── LightCAD.ImportAndExport/         # 导入导出
│   ├── LightCAD.Component.Actions/       # 组件操作
│   ├── LightCAD.PrjManager/             # 项目管理
│   ├── LightCAD.LocalSolution/          # 本地方案
│   ├── LightCAD.DBHelper/               # 数据库帮助
│   ├── LightCAD.DBUtility/              # 数据库工具
│   │
│   ├── Libs/                             # 第三方DLL库
│   │   ├── ThreeJs4Net.dll              # Three.js .NET封装
│   │   ├── OpenTK.dll                   # OpenGL绑定
│   │   └── ...
│   │
│   ├── Plugins/                          # 预编译行业插件
│   │   ├── QdArch.dll                   # 建筑插件（591KB）
│   │   ├── QdElectric.dll               # 电气插件（45KB）
│   │   ├── QdHvac.dll                   # 暖通插件（95KB）
│   │   ├── QdStruct.dll                 # 结构插件（173KB）
│   │   └── QdWater.dll                  # 给排水插件（201KB）
│   │
│   ├── ThirdParty/                       # 第三方源码
│   │   ├── Weikio.PluginFramework/      # 插件框架
│   │   ├── Flee/                         # 表达式求值
│   │   ├── RhinoInside/                 # Rhino集成
│   │   └── Svg/                          # SVG支持
│   │
│   └── netDxf/                           # DXF处理库源码
│
├── test/                                 # 测试项目
│   ├── LightCAD.MathLib.Tests/          # 数学库单元测试
│   └── WinFormTest/                     # 窗体功能测试
│
└── QuickStart/                           # 快速入门示例

2.5 解决方案配置详解

2.5.1 解决方案文件

LightCAD1.sln是Visual Studio解决方案文件，包含了所有项目的引用和构建配置。使用Visual Studio打开此文件后，可以在解决方案资源管理器中看到完整的项目层次结构。

2.5.2 项目依赖关系

项目之间的依赖关系遵循分层架构原则：

LightCAD.WinForm
    ├── LightCAD.Runtime
    │   ├── LightCAD.Drawing
    │   │   ├── LightCAD.RenderUtils
    │   │   │   └── LightCAD.Core
    │   │   │       └── LightCAD.MathLib
    │   │   └── LightCAD.Core
    │   ├── LightCAD.RenderUtils
    │   └── LightCAD.Core
    ├── LightCAD.Model
    │   ├── LightCAD.Runtime
    │   └── LightCAD.Core
    ├── LightCAD.ImportAndExport
    ├── LightCAD.Component.Actions
    └── LightCAD.PrjManager

2.5.3 项目文件（.csproj）配置

以LightCAD.MathLib项目为例，其.csproj文件的关键配置如下：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="MathNet.Numerics" Version="5.0.0" />
  </ItemGroup>
</Project>

关键配置项说明：

• TargetFramework：指定目标框架为.NET 10
• Nullable：启用可空引用类型检查
• ImplicitUsings：启用隐式using声明
• GenerateDocumentationFile：生成XML文档文件

对于依赖Windows平台的项目（如WinForm），目标框架使用net10.0-windows：

<TargetFramework>net10.0-windows</TargetFramework>
<UseWindowsForms>true</UseWindowsForms>

2.6 NuGet包管理

2.6.1 NuGet包依赖

LightCAD的NuGet包依赖相对精简，主要包括：

<!-- 数学运算 -->
<PackageReference Include="MathNet.Numerics" Version="5.0.0" />

<!-- 图形基元 -->
<PackageReference Include="System.Drawing.Common" Version="8.0.1" />

<!-- 实时通信 -->
<PackageReference Include="Microsoft.AspNetCore.SignalR.Client" Version="9.0.4" />

2.6.2 还原NuGet包

首次打开项目或切换分支后，需要还原NuGet包：

方法一：通过Visual Studio

1. 右键解决方案 → "还原NuGet包"
2. 或者在"工具"→"NuGet包管理器"→"管理解决方案的NuGet包"中操作

方法二：通过命令行

# 在解决方案目录下运行
dotnet restore LightCAD1.sln

2.6.3 本地DLL引用

LightCAD的一些核心依赖以本地DLL的方式提供，位于src/Libs/目录：

• ThreeJs4Net.dll：Three.js的.NET封装
• OpenTK.dll：OpenGL绑定库

这些DLL通过项目文件中的Reference引用：

<ItemGroup>
  <Reference Include="ThreeJs4Net">
    <HintPath>..\Libs\ThreeJs4Net.dll</HintPath>
  </Reference>
  <Reference Include="OpenTK">
    <HintPath>..\Libs\OpenTK.dll</HintPath>
  </Reference>
</ItemGroup>

2.7 编译项目

2.7.1 Debug模式编译

# 命令行编译（Debug）
dotnet build LightCAD1.sln --configuration Debug

# 或者在Visual Studio中按 Ctrl+Shift+B

2.7.2 Release模式编译

# 命令行编译（Release）
dotnet build LightCAD1.sln --configuration Release

2.7.3 常见编译问题及解决

问题1：找不到ThreeJs4Net.dll

error CS0006: 找不到元数据文件 'ThreeJs4Net.dll'

解决：确认src/Libs/目录下存在对应的DLL文件。如果DLL未包含在Git仓库中，需要从发布包中获取。

问题2：.NET SDK版本不匹配

error : The current .NET SDK does not support targeting .NET 10

解决：安装最新的.NET 10 SDK。

问题3：Windows Forms相关错误

error : The project targets 'net10.0-windows' but is being built on a non-Windows platform

解决：LightCAD的WinForm项目仅支持在Windows上编译，确保在Windows平台进行开发。

问题4：NuGet包还原失败

error NU1301: Unable to load the service index for source

解决：检查网络连接，或配置NuGet镜像源。国内开发者可以使用华为或阿里云的NuGet镜像。

2.8 运行与调试

2.8.1 设置启动项目

1. 在解决方案资源管理器中，右键LightCAD.WinForm项目
2. 选择"设为启动项目"
3. 启动项目名称变为加粗显示

2.8.2 调试运行

• 按 F5 启动调试（或点击工具栏的绿色播放按钮）
• 按 Ctrl+F5 不调试直接运行

2.8.3 调试技巧

断点调试：

在关键代码处设置断点，例如：

• LightCAD.Core中的实体创建方法
• LightCAD.Drawing中的视口渲染方法
• LightCAD.Runtime中的视图构建器

条件断点：

对于频繁调用的方法（如渲染循环），使用条件断点避免频繁中断：

1. 右键断点 → "条件"
2. 设置触发条件，如 entityCount > 100

输出窗口：

利用Debug.WriteLine()在输出窗口显示调试信息，不影响正式发布版本的性能。

2.9 Git版本控制配置

2.9.1 .gitignore配置

确保.gitignore文件包含以下内容，避免将编译产物提交到仓库：

# Build results
bin/
obj/

# Visual Studio
.vs/
*.user
*.suo

# NuGet
packages/

# OS files
Thumbs.db
.DS_Store

2.9.2 分支管理建议

对于LightCAD的开发，建议采用以下分支策略：

• main：稳定的主分支
• develop：开发分支
• feature/xxx：功能分支
• bugfix/xxx：修复分支
• release/x.x：发布分支

2.10 开发工具推荐

2.10.1 Visual Studio扩展

扩展名称	用途
ReSharper	代码分析和重构
CodeMaid	代码清理和格式化
XAML Styler	AXAML格式化
GitLens	Git增强功能

2.10.2 辅助工具

工具	用途
dnSpy	.NET反编译和调试
ILSpy	IL代码查看
dotPeek	JetBrains反编译工具
PerfView	性能分析
WinDbg	Windows底层调试
RenderDoc	GPU渲染调试

2.11 项目配置最佳实践

2.11.1 代码风格配置

建议在解决方案根目录创建.editorconfig文件，统一团队的代码风格：

[*.cs]
# 缩进设置
indent_style = space
indent_size = 4

# 使用var关键字
csharp_style_var_for_built_in_types = true
csharp_style_var_when_type_is_apparent = true

# 花括号样式
csharp_new_line_before_open_brace = all

# 命名规范
dotnet_naming_rule.public_members_must_be_capitalized.severity = warning
dotnet_naming_rule.public_members_must_be_capitalized.symbols = public_symbols
dotnet_naming_rule.public_members_must_be_capitalized.style = first_word_upper_case_style

2.11.2 构建版本管理

LightCAD使用自定义的.lbuild文件来管理构建版本号。每次编译时版本号会自动递增，便于追踪和回溯问题。

2.11.3 文档生成

由于项目启用了GenerateDocumentationFile选项，编译时会同时生成XML文档文件。在编写代码时，建议为所有公开的类和方法添加XML注释：

/// <summary>
/// 创建一条从起点到终点的直线实体
/// </summary>
/// <param name="startPoint">直线的起始点</param>
/// <param name="endPoint">直线的终止点</param>
/// <returns>创建的直线实体对象</returns>
public LcLine CreateLine(Point2d startPoint, Point2d endPoint)
{
    // ...
}

2.12 本章小结

本章详细介绍了LightCAD开发环境的搭建过程，包括硬件和软件要求、Visual Studio的安装配置、源代码获取、项目结构解析、NuGet包管理、编译调试流程以及开发工具推荐。正确搭建开发环境是顺利进行后续学习和开发的前提，请确保所有环境配置完成并能够成功编译和运行项目。

---

上一章：第一章：LightCAD概述与入门

下一章：第三章：核心架构与分层设计