Как программно добавить присоединённые файлы к документу 1С

Присоединённые файлы в 1С — это механизм хранения произвольных файлов (сканов, изображений, договоров, актов), привязанных к объектам информационной базы: документам, справочникам, задачам. В типовых конфигурациях на базе Библиотеки стандартных подсистем (БСП) за это отвечает подсистема «Работа с файлами», а программный интерфейс предоставляет общий модуль РаботаСФайлами (в старых версиях — ПрисоединенныеФайлы).

Программное добавление файлов нужно при интеграциях: загрузке сканов из внешней системы, прикреплении PDF-счетов при обмене, массовой загрузке фотографий номенклатуры, сохранении сформированных печатных форм. Ручное прикрепление через интерфейс в таких сценариях неприемлемо из-за объёмов.

Ключевой метод — РаботаСФайлами.ДобавитьФайл(), который принимает владельца, двоичные данные или адрес во временном хранилище и возвращает ссылку на элемент справочника присоединённых файлов. Ниже разобраны подготовка, варианты вызова, хранение в томах и типичные ошибки.

Как устроено хранение присоединённых файлов в 1С

В конфигурациях на БСП для каждого типа владельца создаётся отдельный справочник присоединённых файлов, например СчетНаОплатуПокупателюПрисоединенныеФайлы или РеализацияТоваровУслугПрисоединенныеФайлы. Каждый элемент такого справочника содержит ссылку на владельца, имя файла, расширение, размер, дату и служебные поля.

Сами двоичные данные по умолчанию хранятся в информационной базе — в реквизите типа ХранилищеЗначения или в регистре сведений двоичных данных (зависит от версии БСП). Альтернатива — хранение в томах на диске: в базе остаётся только путь к файлу, а содержимое лежит в сетевом каталоге. Тома настраиваются в разделе администрирования.

Понимать структуру важно, потому что от неё зависит выбор метода: если конфигурация на БСП — используйте РаботаСФайлами; если подсистемы нет (самописная конфигурация) — придётся создавать собственный справочник и писать в него напрямую.

Подготовка: что проверить перед написанием кода

Сначала убедитесь, что подсистема работы с файлами включена. В типовых конфигурациях откройте настройки и проверьте функциональную опцию, отвечающую за хранение файлов. Если у документа в интерфейсе нет кнопки «Присоединенные файлы» — подсистема не подключена к этому типу объекта, и программный вызов тоже не сработает.

Второй шаг — определить точное имя справочника присоединённых файлов для вашего документа. Его можно посмотреть в конфигураторе или получить программно через методы БСП. Имя формируется по шаблону: имя объекта-владельца плюс суффикс «ПрисоединенныеФайлы».

Третий момент — права. Пользователь, от имени которого выполняется код (в том числе пользователь фонового задания или веб-сервиса), должен иметь права на добавление элементов справочника присоединённых файлов и на чтение документа-владельца. При вызове из внешнего соединения это частая причина молчаливых сбоев.

Базовый способ: метод РаботаСФайлами.ДобавитьФайл

Основной сценарий выглядит так: двоичные данные файла помещаются во временное хранилище, затем вызывается метод добавления с указанием владельца. Минимальный пример на сервере:

ДвоичныеДанные = Новый ДвоичныеДанные("C:\Files\dogovor.pdf");
АдресХранилища = ПоместитьВоВременноеХранилище(ДвоичныеДанные);

ПараметрыФайла = Новый Структура;
ПараметрыФайла.Вставить("ВладелецФайлов", ДокументСсылка);
ПараметрыФайла.Вставить("Автор", Пользователи.ТекущийПользователь());
ПараметрыФайла.Вставить("ИмяБезРасширения", "Договор");
ПараметрыФайла.Вставить("РасширениеБезТочки", "pdf");
ПараметрыФайла.Вставить("ВремяИзмененияУниверсальное", ТекущаяУниверсальнаяДата());

ПрисоединенныйФайл = РаботаСФайлами.ДобавитьФайл(
ПараметрыФайла, АдресХранилища);

В разных версиях БСП сигнатура метода отличается: в старых релизах параметры передаются позиционно (владелец, имя, расширение и т.д.), в новых — структурой. Перед написанием кода откройте модуль РаботаСФайлами в конфигураторе и посмотрите актуальную сигнатуру именно вашей версии — это избавит от ошибок «Несоответствие числа параметров».

После выполнения метод возвращает ссылку на созданный элемент справочника присоединённых файлов. Сохраните её, если файл нужно будет позже найти, заменить или удалить — искать по имени файла ненадёжно, так как имена могут повторяться.

1. 1
   Получите двоичные данные файла: с диска, из HTTP-ответа или из хранилища значений
2. 2
   Поместите данные во временное хранилище функцией ПоместитьВоВременноеХранилище
3. 3
   Сформируйте структуру параметров: владелец, имя без расширения, расширение, автор
4. 4
   Вызовите РаботаСФайлами.ДобавитьФайл и сохраните возвращённую ссылку
5. 5
   Проверьте результат: откройте документ и убедитесь, что файл виден и открывается

Добавление файла с клиента и из внешних источников

Интерактивный выбор файла пользователем

Если файл выбирает пользователь в тонком клиенте, на клиенте нельзя напрямую читать файловую систему синхронными методами в веб-клиенте. Используйте асинхронный механизм НачатьПомещениеФайла: файл помещается во временное хранилище, после чего управление передаётся на сервер, где вызывается ДобавитьФайл.

Типичная ошибка здесь — попытка вызвать Новый ДвоичныеДанные(Путь) на клиенте в веб-клиенте: метод недоступен, и код падает. Всегда разделяйте код: получение файла — на клиенте через асинхронные методы, создание присоединённого файла — в серверной процедуре.

Загрузка из внешней системы или фоновым заданием

При интеграции через HTTP-сервис или регламентное задание двоичные данные обычно приходят в теле запроса или читаются с сетевого ресурса. В этом случае код полностью серверный: получили данные, поместили в хранилище, вызвали ДобавитьФайл. Обратите внимание: фоновое задание выполняется под служебным пользователем — поле «Автор» заполняйте явно, иначе получите пустого автора или ошибку.

При массовой загрузке (тысячи файлов) оборачивайте каждый файл в отдельную транзакцию или обрабатывайте пачками с обработкой исключений: один битый файл не должен останавливать всю загрузку. Ошибки логируйте в журнал регистрации с указанием имени файла и владельца.

Функция ПрикрепитьФайлКДокументу(ДокументСсылка, ДвоичныеДанные, ИмяФайла)
	Части = СтрРазделить(ИмяФайла, ".");
	Расширение = Части[Части.ВГраница()];
	Адрес = ПоместитьВоВременноеХранилище(ДвоичныеДанные);
	ПараметрыФайла = Новый Структура;
	ПараметрыФайла.Вставить("ВладелецФайлов", ДокументСсылка);
	ПараметрыФайла.Вставить("Автор", Пользователи.ТекущийПользователь());
	ПараметрыФайла.Вставить("ИмяБезРасширения", СтрЗаменить(ИмяФайла, "." + Расширение, ""));
	ПараметрыФайла.Вставить("РасширениеБезТочки", Расширение);
	ПараметрыФайла.Вставить("ВремяИзмененияУниверсальное", ТекущаяУниверсальнаяДата());
	Возврат РаботаСФайлами.ДобавитьФайл(ПараметрыФайла, Адрес);
КонецФункции

Конфигурация без БСП: собственный механизм хранения

В самописных конфигурациях без Библиотеки стандартных подсистем модуля РаботаСФайлами нет. Типовое решение — создать справочник «ФайлыДокументов» с реквизитами: Владелец (ссылка на документы), ИмяФайла, Расширение и ДанныеФайла типа ХранилищеЗначения. Программное добавление сводится к созданию элемента справочника:

НовыйФайл = Справочники.ФайлыДокументов.СоздатьЭлемент();
НовыйФайл.Владелец = ДокументСсылка;
НовыйФайл.ИмяФайла = "Скан акта.pdf";
НовыйФайл.ДанныеФайла = Новый ХранилищеЗначения(ДвоичныеДанные,
Новый СжатиеДанных(9));
НовыйФайл.Записать();

Используйте сжатие данных при помещении в хранилище значений — это заметно сокращает рост базы при хранении сканов и изображений. Учтите ограничение: хранение больших файлов внутри базы ускоряет её раздувание и замедляет резервное копирование. При объёмах от нескольких гигабайт планируйте вынос в тома или во внешнее файловое хранилище.

Хранение в томах и контроль результата

Если в настройках включено хранение файлов в томах, метод ДобавитьФайл сам запишет данные на диск и сохранит в базе только путь. Программно различать режимы не нужно — БСП делает это прозрачно. Но при переносе базы или настройке нового сервера проверьте доступность каталога томов для пользователя, под которым работает сервер 1С, иначе файлы «потеряются»: ссылки есть, а содержимое не открывается.

Проверка результата после программного добавления: откройте документ в режиме предприятия, перейдите к присоединённым файлам и откройте файл на просмотр. Программно убедиться в корректности можно, получив данные обратно через РаботаСФайлами.ДвоичныеДанныеФайла(ПрисоединенныйФайл) и сравнив размер с исходным.

Типичные ошибки и их устранение

Первая распространённая проблема — передача в метод пути к файлу вместо адреса временного хранилища. Метод ожидает именно адрес, полученный через ПоместитьВоВременноеХранилище; строка с путём вызовет ошибку или пустой файл.

Вторая ошибка — неправильный разбор имени файла: расширение должно передаваться без точки, а имя — без расширения. Если передать «договор.pdf» целиком в ИмяБезРасширения, получите файл «договор.pdf.pdf». Третья типичная ситуация — дубли при повторном запуске обработки: перед добавлением проверяйте, нет ли уже файла с таким именем у владельца, если дубли недопустимы.

Частые вопросы