Обновлятор-1с. Учимся писать скрипты на OneScript
Обновлятор-1с. Учимся писать скрипты на OneScript
2019-08-28T11:46:40+00:00О чём вообще идёт речь?
Речь идёт о возможности написания скриптов на языке OneScript для автоматизации операций над группой баз вот на этой вкладке обновлятора:
Что такое OneScript?
Проект является независимой кросс-платформенной реализацией виртуальной машины, исполняющей скрипты на языке 1С:Предприятие.
Иными словами, это возможность писать программы на языке 1С без использования платформы 1С:Предприятие.
И это позволяет нам в конечном итоге брать уже готовые куски кода, написанные в конфигураторе и с минимальной адаптацией переносить их в программу на OneScript.
И пусть по словам разработчиков это не главная цель проекта, но я вижу интерес именно в том, чтобы из программы на OneScript подключаться к базе 1С через внешнее соединение и выполнять некоторый полезный код.
Вы спросите — а зачем это вообще надо? Почему бы не написать этот же код в обработке и запускать через 1с стандартным способом?
Но мы ведь говорим об автоматизации и тут есть фундаментальные проблемы:
- нет способа гарантированно запустить базу и выполнить в ней код некоторой внешней обработки (кто сталкивался с этим на практике знает, что слишком многое может пойти не так, начиная с того, что до выполнения обработки просто не дойдёт из-за какого-нибудь модального окна)
- нет простого способа генерировать такую обработку программно, а ведь это может нам понадобиться, если речь идёт о выполнении полезного кода над группой баз
- нет простого способа логировать выполнение этой обработки
Все эти проблемы решает OneScript.
Зачем писать и запускать эти скрипты именно в обновляторе?
Потому что обновлятор берёт на себя ряд непростых вещей, чтобы упростить написание таких скриптов в части взаимодействия с базами.
А именно.
Список баз для обработки
Прямо в обновляторе мы выбираем для какого количества баз нужно запустить написанный нами скрипт:
Передача параметров базы
При выполнении скрипта обновлятор сам передаёт в него необходимые параметры с информацией о текущей базе:
Все эти параметры мы можем использовать в своём скрипте, делая его универсальным для выполнения над любым количеством выбранных баз.
Примеры таких скриптов мы можем найти в списке шаблонов обновлятора:
Предварительная архивация базы
При необходимости обновлятор обеспечит создание резервной копии перед выполнением скрипта:
Эта резервная копия будет согласована с общей системой архивации, то есть её также можно подвергать «тюнингу» в дополнительных настройках обновлятора. Такая копия всегда будет иметь метку «перед опасной операцией».
Блокировка, разблокировка базы
При необходимости обновлятор выполнит полную блокировку базы перед выполнением вашего скрипта и разблокировку после:
И это одна из ключевых «фич» обновлятора — ведь, например, корректное выполнение блокировки серверной базы в общем случае является достаточно нетривиальной задачей.
Нужно «разрулить» текущие подключения пользователей, административные подключения, выполнение фоновых задач. И всё это через общение напрямую с кластером 1с.
Сохранение отчётов
Обновлятор сохраняет историю выполнения таких скриптов в менеджере отчётов.
Как в общем виде:
Так и в детальном:
Уведомление на почту
Если у вас настроены уведомления на почту (все или только при ошибках)…
… то информация о выполнении скриптов (включая детальные отчёты) будет приходить к вам точно также, как и информация о выполнении других операций из обновлятора:
Запуск скрипта по расписанию
Для добавления скрипта в запуск по расписанию следует сохранить сам скрипт:
Далее у нас есть 2 варианта:
1 (быстрый, но не очень удобный способ). При сохранении скрипта мы можем установить опцию «Настроить однократный запуск скрипта …»:
И далее уже отредактировать расписание этого задания непосредственно в планировщике Windows.
2 (чуть более медленный, но самый удобный). После того как вы сохранили скрипт (не добавляя его в планировщик Windows) вернитесь в главное окно Обновлятора на закладку «Настройки программы».
Далее нажмите кнопку «Расписание»…
И создайте задачу с типом операции «Запуск скрипта»:
Укажите ваш сохраненный скрипт по ссылке «выбрать скрипт для запуска…».
Облачный мониторинг
При сохранении скрипта нам также доступна опция для облачного мониторинга его работы — совершенно потрясающая возможность на мой взгляд. Вот здесь подробнее об облачном мониторинге.
Многопоточное выполнение скриптов
О том как запускать скрипт параллельно для нескольких баз подробно рассказывается здесь.
Что ещё полезно изучить перед написанием скриптов?
Ну, конечно же, сам язык 1С. Куда же без него… 
Прежде всего есть вот этот справочник языка 1С с примерами: ссылка.
Также стоит пробежаться по отличиям OneScript от стандартного языка 1С. Их немного (ссылка).
Ну, и наконец, у OneScript есть также свой синтакс-помощник.
Изучать сторонние библиотеки на OneScript (которые также можно подключать в обновлятор) на первом этапе я не советую. Вы сможете вернуться к ним, когда освоитесь с простейшими скриптами в достаточной мере.
Ну, поехали!
Хватит говорить про скрипты — давайте их писать
Изучаем структуру простейшего скрипта
Для этого выберем из шаблонов пункт «1. Привет, база».
В редактор вставится шаблон простейшего скрипта:
Сам скрипт (раскрыть)
#use "updater1c"
// ****************************************************************************
// Переменные модуля
// ****************************************************************************
Перем errors; // Признак того, что при выполнении скрипта были ошибки.
Перем updater; // Обновлятор, через который мы получаем информацию о базе,
// а также вызываем различные функции обновлятора.
Перем connector; // Коннектор для подключения к базе.
Перем v8; // Само подключение к базе через коннектор.
// ****************************************************************************
// Ваш код для выполнения обновлятором
// ****************************************************************************
Процедура Главная()
Сообщить("Привет, " + updater.BaseName);
КонецПроцедуры
// ****************************************************************************
// Служебные процедуры
// ****************************************************************************
Процедура ПриНачалеРаботы()
errors = Ложь;
updater = Новый Updater1C;
// Если в скрипте не планируется использовать
// подключение к базе - просто закомментируйте
// две нижние строки.
connector = Новый COMОбъект("V" + updater.PlatformRelease + ".COMConnector");
v8 = updater.BaseConnect(connector);
КонецПроцедуры
Процедура ПриОкончанииРаботы()
Если v8 <> Неопределено Тогда
Попытка
ОсвободитьОбъект(v8);
v8 = Неопределено;
Исключение
КонецПопытки;
КонецЕсли;
Если connector <> Неопределено Тогда
Попытка
ОсвободитьОбъект(connector);
connector = Неопределено;
Исключение
КонецПопытки;
КонецЕсли;
Если updater <> Неопределено Тогда
Попытка
ОсвободитьОбъект(updater);
updater = Неопределено;
Исключение
КонецПопытки;
КонецЕсли;
ВыполнитьСборкуМусора();
Если errors Тогда
ЗавершитьРаботу(1);
КонецЕсли;
КонецПроцедуры
// ****************************************************************************
// Инициализация и запуск скрипта
// ****************************************************************************
ПриНачалеРаботы();
Попытка
Главная();
Исключение
errors = Истина;
Сообщить(ОписаниеОшибки());
КонецПопытки;
ПриОкончанииРаботы(); |
Описание версии 1.1.1
Проект перешел на semantic versioning с трехзначной идентификацией основного номера релиза. Теперь команде станет проще выпускать релизы, а сообществу — идентифицировать уровни изменений.
Новые возможности
- Добавлена поддерка XML-схем. Реализован класс
XMLСхемаи ему сопутствующие (спасибо yukon39 за масштабную доработку) - Добавлена функциональность «Макетов». Теперь можно упаковывать в EXE не только скриптовый код, но и произвольные данные, а затем обращаться к ним единообразно
- Оптимизирован метод
- Реализована поддержка dynamic в объектах 1Script. Упрощено встраивание в приложения .NET
- Реализована локализация выводимых ошибок в зависимости от языка системы. Добавлен конфигурационный параметр
systemlanguageв oscript.cfg (спасибо alexkmbk). - В СоединениеHTTP всегда используется автоматический редирект. Реализовано свойство
РазрешитьАвтоматическоеПеренаправлениедля управления редиректом (спасибо Vladimir Bondarevskiy) - В соединении HTTP реализована автоматическая распаковка ответов, закодированных в gzip (спасибо Vladimir Bondarevskiy)
- Оптимизирована производительность оператора
Новый - Реализована часть ранее не реализованных методов в классах работы с двоичными данными
- Реализовано управление кодировкой ZIP-архивов. Добавлено системное перечисление
КодировкаИменФайловВZipФайле - Много других мелких улучшений.
Исправление ошибок
Благодаря Michael Rybakin в релизе исправлено множество самых разных ошибок, включая несоответствия поведению 1С на необычных сценариях.- Внутреннее представление даты содержит микросекунды и искажает сравнение дат
- Некорректная работа метода
СписокЗначений.СортироватьПоПредставлению - Исправлена рефлексия типов при работе под Mono+Linux
- Повторяюшиеся имена колонок
ТаблицыЗначенийдобавляются в список колонок - Метод Массив.Вставить расширяет границы массива при вставке за пределы массива
- Не работает конструктор объекта
ЧтениеДанныхиЗаписьДанныхпри указании параметров дальше 2-го - Отсутствовал конструктор массива по фиксированному массиву
- Некорректно отображались значения
СтрокиТаблицыЗначенийв отладчике - Поведение метода
Удалитьструктуры не соответствовало 1С при удалении несуществующего свойства - Некорректное экранирование символов / и \ при работе с JSON
- Некорректное поведение методов
DataReader.ReadIntoBinaryDataBuffer,DataReader.ReadIntoBinaryDataBuffer(Count),MemoryStream.CloseAndGetBinaryData. - Не было реализовано побайтовое сравнение двоичных данных оператором равенства
- Поведение метода Pow для возведения в степень приведено в соответствие с 1С
- Литерал даты из одних нулей в 1С распознается, как корректный. Приведено поведение к 1С
- Строковое представление двоичных данных не работало в Linux. Под Win не соответствовало 1С
- Функция
Форматзависала на некоторых форматных строках - Исправлена ошибка функции
Целна больших числах
OneScript — Документация
Для работы требуется наличие .NET Framework версии 4.5.2 или выше. В среде Linux — Mono версии 5.2 или выше.
Установка программы
Система поставляется в виде типового пакета установки. В окне инсталлятора потребуется указать место, в которое необходимо установить программу. Никакой дополнительной информации вводить не требуется.
Состав компонентов
На данный момент поставка включает в себя 3 основных компонента:
- Консольное приложение oscript.exe, являющееся основным компонентом системы. Предназначено для выполнения текстовых сценариев в консоли, а также для построения отдельных исполняемых файлов (exe).
- Тестовая утилита TestApp.exe, предназначенная для изучения возможностей OneScript
- Библиотека интеграции OneScript с проектом Снегопат — расширением Конфигуратора платформы 1С:Предприятие
- Стандартная библиотека скриптов из репозитария oscript-library
После установки в главном меню Windows будет добавлен ярлык, запускающий тестовую утилиту TestApp.
Файлы сценариев
Каждый сценарий (скрипт) представляет собой текстовый файл, содержащий модуль на языке 1С:Предприятие.
Стандартное расширение файла OneScript — «.os», например, «myprogram.os».
Файл должен иметь кодировку UTF-8, рекомендуется отсутствие метки BOM в начале файла. Возможно также переключение кодировки, в которой записан файл скрипта. Для этого требуется исправить параметр encoding.script в файле настроек приложения (oscript.cfg).
OneScript поставляется как в виде инсталлятора, так и в виде обычного zip-архива. Инсталлятор является рекомендуемым способом установки, поскольку автоматически будут выполнены следующие действия:
- Установлен .NET 4.5.2, если его не было в системе
- Путь к интерпретатору OneScript будет зарегистрирован в системной переменной PATH
- Возможна выборочная установка компонентов
Установка с использованием ZIP-архива
ZIP-архив поставки включает в себя все возможные компоненты и конфигурационные файлы. Достаточно распаковать архив на жесткий диск и OneScript будет готов к работе. Разумеется, при условии, что все зависимости в системе уже установлены.
Установка на Linux.
Отдельной инструкции по установке на Linux нет. Пользователь Линукс и сам кого хочешь научит устанавливать все что нужно 🙂
Предусмотрена поставка в виде deb и rpm пакетов, которые можно скачать со страницы дистрибутивов.
Если программа была установлена через инсталлятор, то для проверки работоспособности можно запустить командную строку (Win+R, cmd.exe) и в консоли написать oscript.
На экран будет выведена справка по параметрам запуска.
###См. также
С чего начать разработку скриптов на OneScript? Первые шаги
После моего доклада на INFOSTART 2017 EVENT COMMUNITY ко мне многие обращались с таким вопросом: с чего начать разработку скриптов на OneScript? В этой статье привожу набор ссылок и некий порядок действий (как его вижу я) для людей, не знакомым с этим инструментом.
Прежде всего хочу сказать, что я не явлюсь автором движка или стандартных библиотек OneScript. Здесь я бы хотел просто рассказать о том пути, который прошел я, чтобы начать разрабатывать на OneScript. Ни в коем случае не настаиваю на истинность или полноту действий. Если кто-либо из причастных захочет что-то добавить или изменить (на что я надеюсь), с радостью добавлю или изменю. Давайте напишем этот мануал вместе!
1. Для начала, предлагаю посмотреть вот это 25-минутное видео (которое я записывал в рамках пятничных вебинаров разработчиков 1С), где «с нуля» создается первый скрипт, а также объясняются все основные понятия:
2. В видео частично повторяются действия, описанные Андреем Овсянкиным в статье «Как решать повседневные задачи с помощью OneScript». Думаю стоит ее прочитать.
3. Далее, обратите внимание на официальный сайт проекта http://oscript.io, в частности на разделы:
4. Наиболее полный список и описание всех имеющихся стандартных библиотек содержится здесь: https://github.com/oscript-library, а обзор некоторых библиотек есть здесь: https://infostart.ru/public/699642/.
5. Все скрипты, в принципе, можно разрабатывать и в NotePad++, но все же удобнее это делать в Visual Studio Code.
6. Задать вопрос авторам:
- По функциональности движка можно здесь: https://gitter.im/EvilBeaver/OneScript
- По стандартным библиотекам здесь: https://gitter.im/EvilBeaver/oscript-library
- По каждому отдельному инструменту также доступно обсуждение в Gitter.
- Про баги и хотелки можно писать в Issues соответствующего репозитория на GitHub.
7. На infostart уже имеется достаточно статей и программ написанных на OneScript. Прогнозирую в будущем создание отдельного пункта в разделах, например, в фильтре «Платформа»:
Ну а пока, можно воспользоваться поиском, для просмотра всех материалов по этой теме.
8. Примеры готовых инструментов (не из числа стандартных библиотек) на OneScript:
9. Еще полезные статьи о OneScript:
Ну и в заключение хочу сказать, что я вам искренне желаю не делать одни и те же действия руками. Не бойтесь изучать новое, не бойтесь заниматься автоматизацией. Это не только полезно, но и очень увлекательно. Удачи!
Смотрите также:
- Как выбрать доменное имя для web-сайта?
Итак, как вам нужно придумать доменное имя для своего блога или сайта. Но как сделать его запоминающимся? Как заставить людей возвращаться на сайт снова и снова? Об этом пойдет речь…
- Сайт своими руками: с чего начать?
В этой статье я расскажу о том, как своими руками сделать точно такой же как у меня сайт. Думаете это очень сложно? Ничего подобного! Просто следуйте инструкциям, и все получится!…
OneScript — Руководство разработчика
1Script разрабатывается группой энтузиастов на безвозмездной основе. Поэтому, мы приветствуем любую помощь проекту. Нам нужен, например, логотип проекта. Вы можете также доработать документацию проекта или изменить какой-то текст на этом сайте. Вы можете доработать этот сайт целиком, например, поменять дизайн или сделать более удобный синтакс-помощник. Иными словами, мы рады любым идеям, не стесняйтесь писать нам.
Свяжитесь с EvilBeaver и сообщите, что хотели бы сделать.
Во-первых, у нас есть открытый список задач: https://github.com/EvilBeaver/OneScript/issues — это по самому движку. Во-вторых, есть библиотека готовых пакетов скриптов и утилит. https://github.com/oscript-library Каждый пакет- по сути, отдельный проект со своим списком задач. Можно развивать и их в том числе.
Берете любую понравившуюся задачу и делаете ее. Потом присылаете pull-request.
Тестирование
Самая важная помощь — это то, что вы пользуетесь результатами наших стараний. Применяйте 1Script в своей работе и присылайте нам отзывы, пожелания, сообщения о найденных ошибках.
Если вы обнаружили ошибку или хотите предложить новую функцию — оставьте заявку в нашем таск-трекере.
Доработка библиотеки скриптов
Полезность языка на 90% определяется наличием готовых инструментов для него. Дорабатывайте или создавайте новые пакеты в библиотеке скриптов.
Скрипты пишутся на языке 1С — это наш с вами знакомый и любимый язык. Доработать что-то и прислать результат нам — это не страшно и не сложно.
По вопросам доработки библиотеки, пишите сюда: https://gitter.im/EvilBeaver/oscript-library
Если у вас есть полезный скрипт — поделитесь им с сообществом!
Доработка исходных кодов проекта
Самый простой способ — взять одну из задач (или создать свою собственную задачу) со страницы Issues и реализовать ее. Для реализации задачи нужно будет завести отдельную ветку в GIT, а когда задача будет решена — прислать pull request.
Мы работаем по процессу, который известен как git-flow. Неплохое описание этого процесса можно почитать по ссылкам:
При начале работы над новой функциональностью инициализируйте новую ветку по формату feature/ на базе текущей ветки develop (в git-flow программы SourceTree это выполняется автоматически) Не закрывайте ветку функциональности, пока Ваш pull-request не будет утвержден.
Помощь в доработке сайта
Нам не помешает любая помощь в доработке и раскрутке данного сайта. Например, если вы видите явную ошибку в устройстве сайта — не стесняйтесь написать нам про это.
Или же, если вы хотите предложить нам бесплатный сервер для хостинга сайта — мы тоже будем рады.
Donations
В конце-концов поддержать проект можно и материально.
Вырученные средства идут на оплату хостинга и доменного имени.
×Поддержи проект!
Инфраструктура проекта использует арендованный сервер, который требует оплаты.
Вы можете поддержать проект, перечислив любую удобную сумму, которая пойдет на оплату сервера и поддержку инфраструктуры.
OneScript — Руководство разработчика
Когда приступаешь к работе над чужим кодом — главное быстро разобраться, где что находится. Давайте попробуем это сделать.
Откроем в Visual Studio файл 1Script.sln и посмотрим на структуру проекта.
Солюшен содержит несколько сборок:
| Сборка | Описание сборки |
|---|---|
| oscript | Консольное exe-приложение, выполняющее сценарии в командной строке |
| ScriptEngine | Ядро движка. Определяет базовые возможности языковых средств. Содержит компилятор и виртуальную машину |
| ScriptEngine.HostedScript | Библиотека, обеспечивающая подключение скриптового движка к исполняющим приложениям (exe). Эта библиотека содержит все прикладные классы (Коллекции, Xml и прочее). |
| ScriptEngine.Snegopat | Обеспечивает интеграцию с проектом «Снегопат» |
| TestApp | Тестовое приложение с графическим интерфейсом. Позволяет писать несложные скрипты и выполнять эксперименты по изучению движка |
Как правило, расширение и развитие функционала должно реализовываться в библиотеке ScriptEngine.HostedScript.dll. Именно там содержатся все классы стандартной библиотеки и именно там нужно добавлять новые классы.
Терминология
| Термин | Описание |
|---|---|
| Компилятор | Совокупность объектов, выполняющих трансляцию языка 1С в байт-код скрипта |
| Виртуальная машина | Объект, непосредственно выполняющий байт-код скрипта. ВМ реализована в классе MachineInstance |
| Программное окружение | Набор всех классов, переменных и функций, видимых из языка. Это набор всех языковых средств, которые может использовать разработчик скрипта. |
| Контекст | элемент программного окружения. Собственно, программное окружение представляет собой набор контекстов, подключенных к виртуальной машине. Все классы, доступные из языка, представляют собой контексты. |
| Глобальный контекст | контекст, который подключен в глобальную область видимости. В результате все его свойства и методы доступны в скрипте как глобальные. |
| Например, если контекст «Массив» подключить в глобальную область видимости, то глобально будут доступны функции Добавить(), Количество() и Получить(). | |
| Глобальный контекст реализован именно как класс. Это обычный класс, но он подключен в глобальную область видимости, за счет чего все его свойства и методы в скрипте видны как глобальные. |
Базовые понятия
IValue — универсальное значение
Каждое значение представлено типом IValue. Поскольку язык 1С слабо типизирован, то IValue может хранить любое значение. Все числа, строки, объекты, все это — экземпляры IValue.
Интерфейс IValue имеет несколько методов, позволяющих «добыть» из него конкретное значение:
- Функция AsString — приводит объект к строке и возвращает ее. Как правило, результат функции аналогичен стандартной ф-ии ToString(), но не обязательно.
- Функция AsNumber — приводит объект к типу decimal, т.е. получает тип Число. Если это невозможно, выбрасывается исключение «Приведение к типу Число невозможно»
- Функции AsDate/AsBoolean выполняют аналогичные приведения значений
- Функция AsObject приводит значение к объектному типу. Выбрасывает исключение «Значение не является значением объектного типа», если тип не является объектом.
IRuntimeContextInstance — базовый объектный тип
Все объекты представлены экземплярами типа IRuntimeContextInstance. Этот тип является самым базовым для любых объектов.
Именно этот интерфейс используется для вызова свойств и методов объектов внутри виртуальной машины. Функция IValue.AsObject() возвращает как раз IRuntimeContextInstance.
IVariable — просто переменная
Переменная хранит внутри какой-то IValue. Вне виртуальной машины IVariable позволяет организовать возврат значения через параметр (выходной параметр метода). об этом позже
Нужно взять одну из задач (или создать свою собственную задачу) со страницы Issues и реализовать ее. Для реализации задачи нужно будет завести отдельную ветку в GIT, а когда задача будет решена — прислать pull request.
Если возникают вопросы по разработке — не стесняйтесь спрашивать прямо в комментариях к выбранной Issue или черезличные сообщения в BitBucket.