saury-revit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Saury Revit 项目创建器

Saury Revit Project Creator

基于

Saury.Revit.Template

dotnet 模板，通过交互式流程创建完整配置的 Revit 2026 插件项目（MVVM + DI 架构）。

Based on the

Saury.Revit.Template

dotnet template, create a fully configured Revit 2026 plugin project (MVVM + DI architecture) through an interactive process.

工作流程

Workflow

按顺序执行以下步骤，每步完成后再进入下一步。

Execute the following steps in order, proceed to the next step only after completing the current one.

第 1 步：交互式确认项目配置

Step 1: Interactive Confirmation of Project Configuration

执行任何命令前，必须向用户确认以下信息：

必问：

项目名称 — 必须是合法 C# 命名空间名（如
```
Acme.WallTools
```
、
```
JD.RevitHelper
```
），默认
```
RevitDemo
```
或
```
RevitTest
```
。该名称将用于解决方案、项目文件夹、命名空间、程序集、addin 文件、Ribbon 选项卡。
项目创建目录 — 默认当前工作目录。

可选（有默认值，仅需确认）： 3. Revit 版本 — 默认

，通过

--RevitVersion

参数指定。

用户确认后，汇总配置让用户做最终确认再执行。

Before executing any commands, you must confirm the following information with the user:

Required Questions:

Project Name — Must be a valid C# namespace name (e.g.,
```
Acme.WallTools
```
,
```
JD.RevitHelper
```
), default is
```
RevitDemo
```
or
```
RevitTest
```
. This name will be used for the solution, project folder, namespace, assembly, addin file, and Ribbon tab.
Project Creation Directory — Defaults to the current working directory.

Optional (with default values, only need confirmation): 3. Revit Version — Default is

, specified via the

--RevitVersion

parameter.

After user confirmation, summarize the configuration and ask for final confirmation before execution.

第 2 步：检查并安装 .NET 环境

Step 2: Check and Install .NET Environment

检测流程（按顺序执行）：

检测 dotnet CLI 是否存在：

bash

where dotnet

若命令存在，检测 SDK 版本：

bash

dotnet --list-sdks

检查输出中是否包含

8.0

或更高版本的 SDK。

判断结果：
- dotnet CLI 存在且 SDK 8.0+ 已安装 → 跳过，进入下一步
- dotnet CLI 存在但无 SDK 或版本不足 → 需要安装 SDK
- dotnet CLI 不存在 → 需要完整安装

安装方式（按优先级尝试）：

bash

winget install Microsoft.DotNet.SDK.8

安装完成后重新验证：
```
where dotnet && dotnet --list-sdks
```
若
```
winget
```
不可用，改用官方脚本安装：

powershell

Invoke-WebRequest -Uri https://dot.net/v1/dotnet-install.ps1 -OutFile dotnet-install.ps1
./dotnet-install.ps1 -Channel 8.0

若以上方式均失败，告知用户手动下载 .NET 8.0 SDK

Detection Process (execute in order):

Check if dotnet CLI exists:

bash

where dotnet

If the command exists, check SDK version:

bash

dotnet --list-sdks

Check if the output includes SDK version

8.0

or higher.

Judgment Results:
- dotnet CLI exists and SDK 8.0+ is installed → Skip, proceed to next step
- dotnet CLI exists but no SDK or version is insufficient → Need to install SDK
- dotnet CLI does not exist → Need full installation

Installation Methods (try in priority order):

bash

winget install Microsoft.DotNet.SDK.8

Re-verify after installation:
```
where dotnet && dotnet --list-sdks
```
If
```
winget
```
is unavailable, use the official script for installation:

powershell

Invoke-WebRequest -Uri https://dot.net/v1/dotnet-install.ps1 -OutFile dotnet-install.ps1
./dotnet-install.ps1 -Channel 8.0

If the above methods all fail, inform the user to download .NET 8.0 SDK manually

第 3 步：安装模板

Step 3: Install Template

bash

undefined

bash

undefined

检查是否已安装

Check if already installed

dotnet new list saury-revit


- 若已安装 → 跳过，告知用户当前已安装
- 若未安装 → 执行安装：

```bash
dotnet new install Saury.Revit.Template

若需更新 →

dotnet new install Saury.Revit.Template --force

dotnet new list saury-revit


- If already installed → Skip, inform the user it's already installed
- If not installed → Execute installation:

```bash
dotnet new install Saury.Revit.Template

If update is needed →

dotnet new install Saury.Revit.Template --force

第 4 步：创建项目

Step 4: Create Project

bash

dotnet new saury-revit -n <项目名称> -o <输出目录>

参数	说明	示例
`-n`	项目名称（替换所有 `Saury.Revit.Template` ）	`Acme.WallTools`
`-o`	输出目录	`./Acme.WallTools`
`--RevitVersion`	Revit 版本（默认 2026）	`2026`

模板自动完成：

全局替换
```
Saury.Revit.Template
```
→ 用户项目名
自动生成唯一 GUID 替换
```
ADDIN-GUID-PLACEHOLDER
```

排除

.template.config/

、

bin/

、

obj/

、

.vs/

、

Logs/

、

*.user

bash

dotnet new saury-revit -n <Project Name> -o <Output Directory>

Parameter	Description	Example
`-n`	Project Name (replaces all instances of `Saury.Revit.Template` )	`Acme.WallTools`
`-o`	Output Directory	`./Acme.WallTools`
`--RevitVersion`	Revit Version (default 2026)	`2026`

Template Auto-Completion:

Global replacement of
```
Saury.Revit.Template
```
→ User's project name
Automatically generate unique GUID to replace
```
ADDIN-GUID-PLACEHOLDER
```

Exclude

.template.config/

bin/

obj/

.vs/

Logs/

*.user

第 5 步：验证项目结构

Step 5: Verify Project Structure

创建后，列出目录确认结构完整：

<项目名称>/
├── <项目名称>.slnx
└── <项目名称>/
    ├── Commands/AboutCommand.cs
    ├── Extensions/DataContextExtension.cs
    ├── Models/AboutInfo.cs
    ├── ViewModels/AboutViewModel.cs
    ├── Views/AboutView.xaml(.cs)
    ├── Resources/Icons/about.png
    ├── Resources/Styles/ButtonStyles.xaml
    ├── Services/Interfaces/
    ├── Application.cs
    ├── Host.cs
    ├── appsettings.json
    ├── <项目名称>.addin
    └── <项目名称>.csproj

After creation, list the directory to confirm the structure is complete:

<Project Name>/
├── <Project Name>.slnx
└── <Project Name>/
    ├── Commands/AboutCommand.cs
    ├── Extensions/DataContextExtension.cs
    ├── Models/AboutInfo.cs
    ├── ViewModels/AboutViewModel.cs
    ├── Views/AboutView.xaml(.cs)
    ├── Resources/Icons/about.png
    ├── Resources/Styles/ButtonStyles.xaml
    ├── Services/Interfaces/
    ├── Application.cs
    ├── Host.cs
    ├── appsettings.json
    ├── <Project Name>.addin
    └── <Project Name>.csproj

第 6 步：构建验证

Step 6: Build Verification

bash

cd <输出目录>
dotnet restore
dotnet build --configuration Debug_R26

关键：本项目使用

Debug_R26

Release_R26

，禁止使用标准

Debug

Release

，否则构建失败。

构建成功后，编译产物自动复制到

C:\ProgramData\Autodesk\Revit\Addins\2026\

。

bash

cd <Output Directory>
dotnet restore
dotnet build --configuration Debug_R26

Critical Note: This project uses

Debug_R26

Release_R26

, do not use the standard

Debug

Release

, otherwise the build will fail.

After successful build, the compiled artifacts are automatically copied to

C:\ProgramData\Autodesk\Revit\Addins\2026\

第 7 步：告知用户如何使用

Step 7: Inform User on How to Use

构建成功后，向用户展示以下使用说明：

After successful build, display the following usage instructions to the user:

调试启动配置

Debug Launch Configuration

修改 Revit 路径 — 打开
```
<项目名称>.csproj
```
，找到
```
StartProgram
```
属性，确认路径指向本机 Revit 安装位置：

xml

<StartProgram>C:\Program Files\Autodesk\Revit 2026\Revit.exe</StartProgram>

若 Revit 安装在非默认路径，需修改为实际路径。

用 Visual Studio 或 Rider 打开
```
<项目名称>.slnx
```
选择构建配置
```
Debug_R26
```
（工具栏下拉框，不要选
```
Debug
```
）
点击启动/F5 — 自动编译 → 产物复制到 Addins 目录 → 启动 Revit → 附加调试器
Revit 启动后 — 在 Ribbon 选项卡中找到插件按钮，点击即可触发断点调试

Modify Revit Path — Open
```
<Project Name>.csproj
```
, find the
```
StartProgram
```
property, confirm the path points to the local Revit installation location:

xml

<StartProgram>C:\Program Files\Autodesk\Revit 2026\Revit.exe</StartProgram>

If Revit is installed in a non-default path, modify it to the actual path.

Open
```
<Project Name>.slnx
```
with Visual Studio or Rider
Select build configuration
```
Debug_R26
```
(toolbar dropdown, do not select
```
Debug
```
)
Click Start/F5 — Automatic compilation → Artifacts copied to Addins directory → Launch Revit → Attach debugger
After Revit starts — Find the plugin button in the Ribbon tab, click it to trigger breakpoint debugging

后续定制

Subsequent Customization

厂商信息（
```
<项目名称>.addin
```
）— VendorId、VendorDescription、VendorEmail
关于页信息（
```
Models/AboutInfo.cs
```
）— GiteeUrl、Description
添加新功能 — 参见 architecture.md

Vendor Information (
```
<Project Name>.addin
```
) — VendorId, VendorDescription, VendorEmail
About Page Information (
```
Models/AboutInfo.cs
```
) — GiteeUrl, Description
Add New Features — Refer to architecture.md

添加新功能

Add New Features

当用户要求在已创建的项目中添加新功能时，阅读 references/architecture.md 获取完整的代码模板和规则约束，严格按照 A→F 六步流程执行：

Model →
```
Models/
```
目录

ViewModel →

ViewModels/

目录（

partial class

，继承

ObservableObject

）

View →
```
Views/
```
目录（构造函数注入 ViewModel）

Command →

Commands/

目录（

[Transaction(TransactionMode.Manual)]

）

DI 注册 →
```
Host.cs
```
（
```
AddTransient
```
）
Ribbon 按钮 →
```
Application.cs
```
的
```
CreateRibbon
```
方法

When users request to add new features to an existing project, read architecture.md to get complete code templates and rule constraints, and strictly follow the 6-step process from A to F:

Model →
```
Models/
```
directory
ViewModel →
```
ViewModels/
```
directory (partial class, inherits
```
ObservableObject
```
)
View →
```
Views/
```
directory (constructor injects ViewModel)

Command →

Commands/

directory (

[Transaction(TransactionMode.Manual)]

)

DI Registration →
```
Host.cs
```
(
```
AddTransient
```
)
Ribbon Button →
```
CreateRibbon
```
method in
```
Application.cs
```

禁止事项

Prohibited Actions

禁止使用
```
Debug
```
/
```
Release
```
配置，只能用
```
Debug_R26
```
/
```
Release_R26
```
禁止手动
```
new
```
View 或 ViewModel，必须通过
```
Host.GetService<T>()
```
获取
禁止在 View code-behind 中编写业务逻辑
禁止在 ViewModel 中直接调用
```
MessageBox
```
或操作
```
Window
```
禁止硬编码配置值，使用
```
appsettings.json
```
+
```
IOptions<T>
```
除非用户明确要求，不要删除示例 About 功能

Do not use
```
Debug
```
/
```
Release
```
configurations, only use
```
Debug_R26
```
/
```
Release_R26
```
Do not manually
```
new
```
View or ViewModel, must obtain via
```
Host.GetService<T>()
```
Do not write business logic in View code-behind
Do not directly call
```
MessageBox
```
or operate
```
Window
```
in ViewModel
Do not hardcode configuration values, use
```
appsettings.json
```
+
```
IOptions<T>
```
Unless explicitly requested by the user, do not delete the sample About feature