# Сборка и подключение BulkArchiveMailer

Это решение написано и ни разу не собрано в среде без Windows/Visual
Studio/.NET SDK — весь код написан вручную по памяти о реальных
VSTO/Outlook Interop API, но **первая сборка обязательно должна пройти на
вашей машине**, прежде чем этому плагину можно будет доверять. Ниже —
пошаговая инструкция и список мест, где по опыту чаще всего что-то не
сходится при первом открытии вручную написанного `.csproj`.

## Требования

- Windows 10/11.
- Классический Outlook (Win32 или Microsoft 365 C2R) — **не** "новый
  Outlook" (он не поддерживает VSTO).
- Visual Studio 2022 (Community — бесплатная) с установленным workload'ом
  **".NET desktop development"** И **"Office/SharePoint development"**
  (последний ставит шаблоны VSTO, VSTO Runtime и Office Developer Tools —
  без него сборка `BulkArchiveMailer.AddIn` не найдёт
  `Microsoft.Office.Tools.*` сборки).
- Установленный **VSTO Runtime** (обычно ставится вместе с
  Office/SharePoint workload'ом; если Outlook жалуется на "not a valid
  Office Add-in" при загрузке — скорее всего он не установлен отдельно,
  доустановите "Microsoft Visual Studio 2010 Tools for Office Runtime" /
  актуальную версию VSTO Runtime).

## Открытие и сборка

1. Откройте `BulkArchiveMailer.sln` в Visual Studio.
2. Дайте NuGet восстановить пакеты (`BulkArchiveMailer.Core.Tests` тянет
   xUnit + `Microsoft.NET.Test.Sdk`; `BulkArchiveMailer.Core` и
   `BulkArchiveMailer.AddIn` NuGet-пакетов не используют вовсе — это
   осознанное решение, см. `AppSettings.cs`, чтобы не зависеть от
   восстановления пакетов в непроверенной среде).
3. Соберите решение (Build → Build Solution). Скорее всего первая сборка
   пройдёт чисто, но если нет — см. раздел "Типичные проблемы" ниже.
4. `BulkArchiveMailer.Core.Tests` можно запустить через Test Explorer —
   там сейчас один smoke-тест (`FilenameParserTests`), подтверждающий, что
   тестовый проект в принципе собирается и видит `Core`. Полное покрытие
   тестами — отдельная задача (dotnet-tester), не часть этой сборки.

## Отладка (F5)

Проект `BulkArchiveMailer.AddIn` настроен как VSTO Outlook Add-in — при
нажатии F5 (с ним как стартовым проектом) Visual Studio должна сама
зарегистрировать временную запись в реестре и запустить Outlook с уже
загруженным плагином. Если Outlook уже был открыт — закройте его перед F5.

Кнопка ленты **"Массовая рассылка"** появляется на вкладке "Главная"
основного окна Outlook (список писем), в группе "ssh-access-tui".

## Установка вне Visual Studio (ручной sideload)

Это внутренний инструмент, поэтому здесь используется **sideload через
реестр**, а не полноценная публикация ClickOnce с веб-сервером или
раскатка через GPO (это отдельная задача на будущее, если понадобится
массово ставить плагин большому числу операторов).

1. Соберите решение в конфигурации Release (Build → Configuration Manager
   → Release, затем Build Solution).
2. В `BulkArchiveMailer.AddIn\bin\Release\` после сборки появятся, среди
   прочего, `BulkArchiveMailer.AddIn.dll` и
   `BulkArchiveMailer.AddIn.vsto` (манифест генерируется автоматически
   MSBuild-таргетами VSTO — в исходниках его нет и не должно быть,
   `.gitignore` его игнорирует).
3. Скопируйте всю папку `bin\Release\` в постоянное место на диске
   оператора (например, `C:\Tools\BulkArchiveMailer\`) — VSTO plug-in
   должен запускаться из стабильного пути, а не из папки сборки, которая
   может быть пересобрана/удалена.
4. Добавьте ключ реестра, которым Outlook находит плагин:

   ```
   [HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\Addins\BulkArchiveMailer.AddIn]
   "Description"="Массовая рассылка архивов ssh-access-tui"
   "FriendlyName"="BulkArchiveMailer"
   "Manifest"="file:///C:\\Tools\\BulkArchiveMailer\\BulkArchiveMailer.AddIn.vsto|vstolocal"
   "LoadBehavior"=dword:00000003
   ```

   (можно сохранить как `.reg`-файл и применить двойным щелчком).
5. Запустите Outlook. Поскольку манифест не подписан сертификатом
   (`SignManifests=false` в `.csproj` — см. комментарий там же о причине),
   при первой загрузке Outlook, скорее всего, покажет предупреждение
   "не удалось проверить издателя" или подобное. Варианты:
   - принять предупреждение вручную (для одного оператора это разумно);
   - добавить папку с плагином в доверенные расположения для VSTO:
     `HKEY_CURRENT_USER\Software\Microsoft\VSTO\Security\Trust Manager\TrustedFolders\<любой уникальный ключ>` = путь к папке с `.vsto`, `String` REG_SZ.
   - для более широкой раскатки — подписать манифест сертификатом
     (Project Properties → Signing в Visual Studio) и настроить
     доверие централизованно (GPO/сертификат в доверенных издателях) —
     это уже упомянутое будущее развитие, не сделано в этой версии.

## Типичные проблемы при первом открытии

Поскольку `.csproj`/`.sln` в этом решении написаны вручную (без мастера
Visual Studio, из-за отсутствия здесь Windows/VS/.NET SDK для
генерации), возможны мелкие расхождения с тем, что сгенерировал бы
реальный мастер "Outlook VSTO Add-in". Если сборка `BulkArchiveMailer.AddIn`
падает на ссылках `Microsoft.Office.*`/`Microsoft.VisualStudio.Tools.*`:

1. Проверьте, что workload "Office/SharePoint development" точно
   установлен (Visual Studio Installer → Modify).
2. Если конкретная ссылка подсвечена жёлтым в Solution Explorer — правой
   кнопкой на неё → Properties → сверьте путь; как правило, достаточно
   удалить и заново добавить через Add Reference → Assemblies →
   Extensions, найдя те же имена (`Microsoft.Office.Tools.Outlook` и
   т.д.) — они должны там появиться, если workload установлен.
3. Если `Microsoft.Office.Interop.Outlook`/`office` не резолвятся с
   версией `15.0.0.0` — это нормально расходится в зависимости от того,
   какая версия Office PIA установлена; смените `Version=` в ссылке (в
   `.csproj`, ищите `Microsoft.Office.Interop.Outlook`/`office`) на
   установленную (`14.0.0.0` для Office 2010 PIA и т.п.) либо просто
   удалите атрибут версии в Solution Explorer и добавьте заново через
   Add Reference — Visual Studio подставит то, что реально стоит на
   машине.
4. TargetFrameworkVersion `v4.8` требует установленного .NET Framework 4.8
   Developer Pack — Visual Studio предложит установить его сама при
   открытии, если его нет.

Ничего из перечисленного не проверялось вживую — список составлен по
опыту работы с VSTO-проектами в целом, а не по факту увиденной ошибки в
этом конкретном решении.