Skip to content

ExportIFC_developer_guide.md

Latest commit

 

History

History
270 lines (191 loc) · 13.5 KB

ExportIFC_developer_guide.md

File metadata and controls

270 lines (191 loc) · 13.5 KB

ExportIFCFromRevit-CSharp — руководство для разработчиков и сопровождающих документацию

Этот документ дополняет основной manual, а не заменяет его.

Основной технический manual остаётся главным источником по настройке, запуску, эксплуатации и диагностике ExportIFC. Этот companion-doc нужен для двух соседних задач:

  • быстро понять карту исходников и рабочие dev-маршруты;
  • поддерживать документацию согласованной с реальным поведением кода.

1. Когда открывать этот документ

Открывайте его, если вам нужно:

  • разобраться, как устроен src/ и какие проекты за что отвечают;
  • локально собирать и ставить add-in из репозитория;
  • понять, какие изменения в коде тянут за собой обновление документации;
  • быстро вспомнить, какие документы в репозитории за что отвечают.

Если задача у вас эксплуатационная, а не разработческая, почти всегда правильнее начинать с основного manual.

2. Быстрая карта репозитория

Базовая раскладка проекта выглядит так:

ExportIFCFromRevit-CSharp/
    README.md
    src/
    _settings/
    admin_data/
    _examples/
    _docs/
    _release_templates/
    _git_images/
    tools/

Коротко по ролям:

  • README.md — входная точка и верхнеуровневая навигация по проекту;
  • src/ — solution и исходный код;
  • _settings/ — пользовательские настройки проекта;
  • admin_data/ — рабочие Excel-файлы, история и логи;
  • _examples/ — шаблоны IFC-конфигов и материалы по их структуре;
  • _docs/ — основной manual и companion-documents;
  • _release_templates/ — package-local шаблоны для release-сборки: сюда входят только те README, wrapper-скрипты и узкие документы, которые нужны именно внутри опубликованных пакетов. Общие settings.ini, Excel-книги, docx и содержимое _examples не дублируются здесь, а подтягиваются workflow из канонических корневых файлов репозитория;
  • _git_images/ — изображения для README и документации;
  • tools/ — dev-инструменты и локальная установка add-in.

Практическая граница простая:

  • настройка и эксплуатация живут в manual, settings.ini, Excel и IFC-конфигах;
  • доработка, локальная сборка, release-упаковка и сопровождение документации живут здесь, в _release_templates/ и в tools/README.md.

3. Карта src/

Типичная структура верхнего уровня:

src/
    ExportIFCFromRevit-CSharp.sln
    Directory.Build.props
    ExportIfc.Common/
    ExportIfc.Orchestrator/
    ExportIfc.RevitAddin.Shared/
    ExportIfc.RevitAddin.Net48/
    ExportIfc.RevitAddin.Net8/
    ExportIfc.Tests/

3.1. ExportIFCFromRevit-CSharp.sln и Directory.Build.props

  • ExportIFCFromRevit-CSharp.sln — основное решение Visual Studio;
  • Directory.Build.props — общие build-настройки для проектов solution.

Это инфраструктурный слой репозитория. С него обычно начинают, если нужно локально собирать, запускать или тестировать проект.

3.2. ExportIfc.Common

Общий библиотечный слой, на котором держатся и orchestrator, и Revit add-in.

Практически здесь живут:

  • общие модели данных;
  • загрузка settings.ini;
  • имена файлов и каталогов;
  • общие Revit- и IO-утилиты;
  • transfer-контракты между orchestrator и add-in.

Если ExportIfc.Orchestrator и ExportIfc.RevitAddin.* считать разными рабочими контурами, то ExportIfc.Common — это их общий язык.

3.3. ExportIfc.Orchestrator

Внешний управляющий контур системы и главная пользовательская точка входа.

Именно здесь сосредоточена логика, которая отвечает на вопросы:

  • какие модели брать в работу;
  • какие модели можно пропустить;
  • какую версию Revit использовать;
  • как сформировать batch-пакет;
  • как запустить Revit и дождаться результата;
  • как читать и обновлять manage.xlsx и history.xlsx.

Если вы разбираете поведение dry-run, отбор моделей, упаковку batch-задач или запуск Revit, чаще всего смотреть нужно сюда.

3.4. ExportIfc.RevitAddin.Shared

Общий исполнительный слой, который уже работает внутри Revit.

Здесь находятся:

  • загрузка batch-контекста;
  • сценарий IFC-экспорта;
  • обработка маршрутов и попыток;
  • логика runner'а;
  • взаимодействие с документами и видами Revit;
  • add-in-логи и шумозащита UI.

Если проблема проявляется уже после старта Revit, то это один из главных кандидатов на разбор.

3.5. ExportIfc.RevitAddin.Net48 и ExportIfc.RevitAddin.Net8

Это тонкие add-in-проекты под разные поколения Revit:

  • ExportIfc.RevitAddin.Net48 — для Revit 2022–2024;
  • ExportIfc.RevitAddin.Net8 — для Revit 2025–2026.

Они не дублируют весь shared-код, а подключают его к нужному runtime-контуру.

3.6. ExportIfc.Tests

Тестовый проект, который страхует проект от регрессий.

При изменениях в отборе моделей, логике history, parsing Excel, маршрутах экспорта и общих контрактах сначала полезно искать или добавлять проверки именно здесь.

4. Практические dev-маршруты

4.1. Нужно локально собрать и поставить add-in

Базовый маршрут такой:

  1. Собрать нужный add-in-проект в x64.
  2. Убедиться, что build-output появился в src/ExportIfc.RevitAddin.* /bin/x64/<Configuration>/.
  3. Установить add-in через tools/install-addin.ps1.
  4. Один раз вручную открыть нужную версию Revit и принять загрузку add-in, если Revit покажет такое окно.

Подробные команды и параметры живут в README по служебным инструментам.

4.2. Нужно проверить поведение orchestrator

Обычно полезно идти в таком порядке:

  1. Проверить код в ExportIfc.Orchestrator.
  2. Сверить ожидания с основным manual.
  3. Прогнать dry-run или ручной запуск.
  4. Проверить, не нужно ли обновлять README и companion-documents.

4.3. Нужно проверить поведение уже внутри Revit

Чаще всего смотреть нужно в:

  • ExportIfc.RevitAddin.Shared;
  • соответствующий add-in-проект Net48 или Net8;
  • batch-артефакты и технические логи из admin_data/_logs/_tech.

Здесь важно не путать две стадии:

  • orchestrator решает, что и как запускать;
  • add-in решает, как именно выполнить экспорт внутри Revit.

5. Как сопровождать документацию

5.1. Роли документов

В проекте полезно держать простое разделение ролей:

  • README.md — обзор, вход и краткая навигация;
  • ExportIFC_manual.md — основной эксплуатационный manual;
  • этот документ — карта исходников и правила согласованного сопровождения;
  • _settings/README.md — краткая памятка по settings.ini;
  • _examples/IFC_Export_Config_structure.md — отдельный документ по IFC-конфигам;
  • tools/README.md — dev-инструменты и локальная установка add-in;
  • _release_templates/ — package-local тексты и wrapper-скрипты для release-пакетов;
  • .github/workflows/release.yml — автоматическая сборка release-пакетов из build-output и канонических файлов репозитория, включая LICENSE.

Хороший признак здоровья документации:

  • manual не расползается в dev-справочник;
  • README не дублирует весь manual;
  • узкие документы не спорят с manual по контрактам проекта.

5.2. Какие изменения в коде почти всегда требуют проверки документации

Почти всегда нужно перепроверять manual и соседние документы, если меняется что-то из этого списка:

  • структура settings.ini и смысл ключей;
  • роль manage.xlsx, history.xlsx и admin_data;
  • связка settings.ini → manage.xlsx → IFC-конфиги;
  • правила отбора моделей на экспорт;
  • контракты dry-run и real-run;
  • сценарий запуска из рабочего корня или через явный путь к settings.ini;
  • transport-логика orchestrator ↔ add-in;
  • batch-артефакты, status-файлы и диагностические логи;
  • правила backup/restore и проверки актуальности IFC.

Если меняется один из таких контрактов, редко бывает достаточно поправить один абзац в одном месте.

5.3. Базовый порядок обновления документации

Полезный рабочий порядок такой:

  1. Сначала проверить фактическое поведение кода.
  2. Затем обновить основной manual как главный эксплуатационный источник.
  3. После этого синхронизировать README репозитория, companion-documents и узкие README, если они описывают тот же контракт.
  4. Если меняется published-раскладка пакетов, синхронизировать _release_templates/ и .github/workflows/release.yml.
  5. В конце перепроверить ссылки, названия сущностей и терминологию.

Так меньше шанс получить ситуацию, когда один документ уже описывает обновлённый контракт, а соседние файлы ещё нет.

6. Мини-чек-лист перед завершением правки

Перед тем как считать изменение законченным, полезно быстро пройтись по списку:

  1. Понятно ли, в каком контуре живёт изменение: orchestrator, add-in, common или tests.
  2. Не меняет ли оно эксплуатационный контракт, описанный в основном manual.
  3. Нужна ли под это изменение новая или обновлённая проверка в ExportIfc.Tests.
  4. Не сломались ли ссылки из manual на companion-documents.
  5. Не противоречат ли друг другу README, manual и узкие документы.

Если на этих пяти вопросах всё согласовано, документация обычно остаётся в здоровом состоянии без лишнего перегрева.