Перейти к содержанию

Создание консольных команд tadmin

Создание консольных команд tadmin

Начиная со сборки 3.4.0 в системе добавлено открытое API для создания собственных консольных команд для утилиты tadmin. Исходный код всех типовых консольных команд доступен для модификации в проектных расширениях Tessa.Extensions.Default.Console. В проекте Tessa.Extensions.Console рекомендуется добавлять новые консольные команды, которые можно использовать в рамках проекта в любых целях интеграции и автоматизации взаимодействия с системой.

Команды, которые создаются в рамках API, разделяют на серверные и клиентские:

  1. Серверные команды не используют контейнер Unity и метаинформацию от веб-сервиса. Им доступно прямое соединение с базой данных в соответствии со строками подключения в app.json. Также они могут выполнять любые другие действия, связанные с файлами и другими локальными ресурсами, например, генерировать ключ токена безопасности (команда GetKey) или упаковывать папку с клиентским приложением в файл карточки .json для возможности последующего импорта карточки на сервер (команда PackageApp).

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

Серверная команда для прямого взаимодействия с БД

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

Откройте решение с проектными расширениями Tessa.Extensions.sln в Visual Studio или другой подходящей IDE, раскройте проект Tessa.Extensions.Console и добавьте туда папку SearchUser. В этой папке будут расположены все необходимые классы для регистрации команды и описания её бизнес-логики.

Создайте класс Operation. В нём описываются действия, выполняемые командой. Метод ExecuteAsync получает управление сразу после проверки корректности переданных аргументов, но при этом соединение с базой данных или другие действия не выполняются автоматически. Соединение с базой данных открывается посредством метода DefaultConsoleHelper.CreateDbManagerAsync, код этого метода открыт в проекте расширений Tessa.Extensions.Default.Console.

Метод возвращает целое число - код возврата из консольной утилиты, которые можно будет проверить в командных файлах (if errorlevel для Windows, $? в bash для Linux). Всегда возвращайте число 0, если всё успешно, или различные отрицательные числа в случае разных ошибок.

using System; using System.Threading.Tasks; using Tessa.Extensions.Default.Console; using Tessa.Platform.ConsoleApps; using Tessa.Platform.Data;

namespace Tessa.Extensions.Console.SearchUser { public static class Operation { public static async Task<int> ExecuteAsync( IConsoleLogger logger, string userLogin, string configurationString, string databaseName) { using (DbManager db = await DefaultConsoleHelper.CreateDbManagerAsync( logger, configurationString, databaseName)) { IQueryBuilderFactory builderFactory = new QueryBuilderFactory(db.GetDbms());

Guid? userID = await db .SetCommand( builderFactory .Select().C("ID") .From("PersonalRoles") .Where().LowerC("Login").Equals().LowerP("Login") .Build(), db.Parameter("Login", userLogin)) .LogCommand() .ExecuteAsync<Guid?>();

if (!userID.HasValue) { logger.Error("Can't find user by login: \"{0}\"'", userLogin); return -1; }

logger.Write(userID.Value.ToString("D")); }

return 0; } } }

Создайте класс Command, в котором указывается название консольной команды [Verb], её аргументы [Argument], текстовое описание команды или аргументов [Description] для вывода в окне справки --help или локализованное описание [LocalizableDescription] (можно использовать только строки локализации, присутствующие в типовой поставке платформы, что применимо в основном для некоторых типовых аргументов).

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

using System.ComponentModel; using System.IO; using System.Threading.Tasks; using NLog; using Tessa.Localization; using Tessa.Platform; using Tessa.Platform.CommandLine; using Tessa.Platform.ConsoleApps;

namespace Tessa.Extensions.Console.SearchUser { public static class Command { [Verb("SearchUser")] [Description("Write user id to standard output searching by login")] public static async Task SearchUser( [Output] TextWriter stdOut, [Error] TextWriter stdErr, [Argument, Description("User login to search.")] string userLogin, [Argument("cs"), LocalizableDescription("Common_CLI_ConfigurationString")] string configurationString = null, [Argument("db"), LocalizableDescription("Common_CLI_DatabaseName")] string databaseName = null, [Argument("q"), LocalizableDescription("Common_CLI_Quiet")] bool quiet = false, [Argument("nologo")] [LocalizableDescription("CLI_NoLogo")] bool nologo = false) { Check.ArgumentNotNullOrEmpty(userLogin, nameof(userLogin));

if (!nologo && !quiet) { ConsoleAppHelper.WriteLogo(stdOut); }

IConsoleLogger logger = new ConsoleLogger( LogManager.GetLogger(nameof(SearchUser)), stdOut, stdErr, quiet);

int result = await Operation.ExecuteAsync( logger, userLogin, configurationString, databaseName);

ConsoleAppHelper.EnvironmentExit(result); } } }

Создайте класс CommandRegistrator для регистрации метода команды, приведённого в предыдущем классе. Обратите внимание, что требуется указать типы всех параметров метода Command.SearchUser в порядке их следования.

using System.IO; using Tessa.Platform.CommandLine; using Tessa.Platform.ConsoleApps;

namespace Tessa.Extensions.Console.SearchUser { [ConsoleRegistrator] public sealed class CommandRegistrator : ConsoleRegistratorBase { public override void RegisterCommands() { this.CommandContext .AddCommand<TextWriter, TextWriter, string, string, string, bool, bool>(Command.SearchUser) ; } } }

Соберите проект расширений Tessa.Extensions.Console. В выходной папке проекта bin\Release\net5.0 (для конфигурации Release) будет доступна собранная сборка с расширением Tessa.Extensions.Console.dll, которую скопируйте с заменой в подпапку extensions в папке с консольной утилитой tadmin (в папке со сборкой это папки Tools для Windows и linux/tools для Linux).

Теперь вы можете выполнить следующие команды, чтобы убедиться, что для консольной команды SearchUser доступна справка, и при поиске сотрудника с логином admin выводится его идентификатор (параметр -q позволяет отключить информационные и служебные сообщения).

tadmin SearchUser --help

tadmin SearchUser admin -q

Клиентская команда для подключения к веб-сервису

Рассмотрим создание команды с именем SelectFromView, которая будет подключаться к веб-сервису с указанными параметрами, выполнять представление с заданным алиасом, а результаты представления вместе с заголовками колонок будут выводится на окно консоли (стандартный вывод, который также можно перенаправить в файл или в стандартный ввод другой команды).

Откройте решение с проектными расширениями Tessa.Extensions.sln в Visual Studio или другой подходящей IDE, раскройте проект Tessa.Extensions.Console и добавьте туда папку SelectFromView. В этой папке будут расположены все необходимые классы для регистрации команды и описания её бизнес-логики.

Создайте класс OperationContext, который будет содержать параметры настройки этой команды, не связанные с подключением к веб-сервису. Здесь это ViewAlias - алиас выполняемого представления, и PageLimit - количество отображаемых строк с первой страницы представления, если представление поддерживает пейджинг.

namespace Tessa.Extensions.Console.SelectFromView { public class OperationContext { public string ViewAlias { get; set; }

public int PageLimit { get; set; } } }

Создайте класс Operation. В нём описываются действия, выполняемые командой. Через конструктор можно получить любые зависимости из клиентского Unity-контейнера, в т.ч. IViewService для взаимодействия с представлениями и ISession для описания открытой сессии текущего пользователя.

Метод ExecuteAsync получает управление уже после того, как был успешно выполнен логин к веб-сервису, и создана сессия. Сессия будет закрыта после выхода из метода.

Метод возвращает целое число - код возврата из консольной утилиты, которые можно будет проверить в командных файлах (if errorlevel для Windows, $? в bash для Linux). Всегда возвращайте число 0, если всё успешно, или различные отрицательные числа в случае разных ошибок.

using System.Collections.Generic; using System.Linq; using System.Threading; using System.Threading.Tasks; using Tessa.Platform; using Tessa.Platform.Collections; using Tessa.Platform.ConsoleApps; using Tessa.Platform.Runtime; using Tessa.Views; using Tessa.Views.Metadata;

namespace Tessa.Extensions.Console.SelectFromView { public sealed class Operation : ConsoleOperation<OperationContext> { public Operation( IViewService viewService, ISession session, IConsoleLogger logger, ConsoleSessionManager sessionManager) : base(logger, sessionManager, extendedInitialization: true) { // параметр extendedInitialization определяет, будет ли выполнены получение метаинформации от сервера // и её инициализация на клиенте; здесь мы используем метаинформацию по представлению this.viewService = viewService; this.session = session; }

private readonly IViewService viewService;

private readonly ISession session;

public override async Task<int> ExecuteAsync( OperationContext context, CancellationToken cancellationToken = default) { if (!this.SessionManager.IsOpened) { return -1; }

this.Logger.Info("Getting metadata for view \"{0}\"", context.ViewAlias);

ITessaView view = this.viewService.GetByName(context.ViewAlias); if (view is null) { this.Logger.Error("Can't acquire metadata for view \"{0}\"", context.ViewAlias); return -1; }

IViewMetadata viewMetadata = view.Metadata; ITessaViewRequest viewRequest = new TessaViewRequest(viewMetadata) { CalculateRowCounting = false };

var viewSpecialParameters = new ViewSpecialParameters( new ViewCurrentUserParameters(this.session), new ViewPagingParameters(), new ViewCardParameters());

var parameters = new List<RequestParameter>(); viewSpecialParameters.ProvideCurrentUserIdParameter(parameters);

if (viewMetadata.Paging != Paging.No && context.PageLimit > 0) { viewSpecialParameters.ProvidePageLimitParameter( parameters, Paging.Always, context.PageLimit, false);

viewSpecialParameters.ProvidePageOffsetParameter( parameters, Paging.Always, 1, context.PageLimit, false); }

viewRequest.Values = parameters;

// получаем данные представления ITessaViewResult viewResult = await view.GetDataAsync(viewRequest, cancellationToken);

string[] columns = (viewResult.Columns ?? EmptyHolder<string>.Array).Cast<string>().ToArray(); this.Logger.WriteLine(string.Join('\t', columns));

IList<object> viewResultRows = viewResult.Rows; if (viewResultRows != null) { foreach (IList<object> row in viewResultRows) { this.Logger.WriteLine( string.Join('\t', row.Select(x => FormattingHelper.FormatToString(x, true)))); } }

return 0; } } }

Создайте класс Command, в котором указывается название консольной команды [Verb], её аргументы [Argument], текстовое описание команды или аргументов [Description] для вывода в окне справки --help или локализованное описание [LocalizableDescription] (можно использовать только строки локализации, присутствующие в типовой поставке платформы, что применимо в основном для некоторых типовых аргументов).

Здесь мы указываем аргумент без имени viewAlias с алиасом выполняемого представления и аргумент -page:XX с ограничением на количество строк, выводимых на первой странице представления, если оно поддерживает пейджинг. Остальные аргументы являются типовыми и используются при подключении к веб-сервису.

using System.ComponentModel; using System.IO; using System.Threading.Tasks; using Tessa.Localization; using Tessa.Platform; using Tessa.Platform.CommandLine; using Tessa.Platform.ConsoleApps; using Unity;

namespace Tessa.Extensions.Console.SelectFromView { public static class Command { [Verb("SelectFromView")] [Description("Write data from view to standard output.")] public static async Task SelectFromView( [Output] TextWriter stdOut, [Error] TextWriter stdErr, [Argument] [Description("View alias to select from.")] string viewAlias, [Argument("a")] [LocalizableDescription("Common_CLI_Address")] string address = null, [Argument("i")] [LocalizableDescription("Common_CLI_Instance")] string instanceName = null, [Argument("u")] [LocalizableDescription("Common_CLI_UserName")] string userName = null, [Argument("p")] [LocalizableDescription("Common_CLI_Password")] string password = null, [Argument("page")] [Description("Page limit for the first page if view allows paging.")] int pageLimit = 20, [Argument("q"), LocalizableDescription("Common_CLI_Quiet")] bool quiet = false, [Argument("nologo")] [LocalizableDescription("CLI_NoLogo")] bool nologo = false) { Check.ArgumentNotNullOrEmpty(viewAlias, nameof(viewAlias));

if (!nologo && !quiet) { ConsoleAppHelper.WriteLogo(stdOut); }

IUnityContainer container = new UnityContainer() .ConfigureConsoleForClient(stdOut, stdErr, quiet, instanceName, address);

int result; using (var operation = container.Resolve<Operation>()) { var context = new OperationContext { ViewAlias = viewAlias, PageLimit = pageLimit, };

if (!await operation.LoginAsync(userName, password)) { ConsoleAppHelper.EnvironmentExit(ConsoleAppHelper.FailedLoginExitCode); }

result = await operation.ExecuteAsync(context); await operation.CloseAsync(); }

ConsoleAppHelper.EnvironmentExit(result); } } }

Создайте класс CommandRegistrator для регистрации метода команды, приведённого в предыдущем классе. Обратите внимание, что требуется указать типы всех параметров метода Command.SelectFromView в порядке их следования.

using System.IO; using Tessa.Platform.CommandLine; using Tessa.Platform.ConsoleApps;

namespace Tessa.Extensions.Console.SelectFromView { [ConsoleRegistrator] public sealed class CommandRegistrator : ConsoleRegistratorBase { public override void RegisterCommands() { this.CommandContext .AddCommand<TextWriter, TextWriter, string, string, string, string, string, int, bool, bool>( Command.SelectFromView) ; } } }

Соберите проект расширений Tessa.Extensions.Console. В выходной папке проекта bin\Release\net5.0 (для конфигурации Release) будет доступна собранная сборка с расширением Tessa.Extensions.Console.dll, которую скопируйте с заменой в подпапку extensions в папке с консольной утилитой tadmin (в папке со сборкой это папки Tools для Windows и linux/tools для Linux).

Теперь вы можете выполнить следующие команды, чтобы убедиться, что для консольной команды SelectFromView доступна справка, и при выполнении представления с алиасом KrDocStates выводятся заголовки колонок и строки представления, в данном случае это список состояний документов (параметр -q позволяет отключить информационные и служебные сообщения). Другой пример для представления с алиасом MyTasks отображает только первые две строки, выводимые представлением, за счёт использования аргумента -page:2.

tadmin SelectFromView --help

tadmin SelectFromView KrDocStates -a:https://localhost/tessa -u:admin -p:admin -q

tadmin SelectFromView MyTasks -page:2 -a:https://localhost/tessa -u:admin -p:admin -q

За примерами исходных кодов для других консольных команд обратитесь к проекту расширений Tessa.Extensions.Default.Console.

Команда tadmin для вычисления хеш-суммы файла

Ниже приведён пример простой команды, не выполняющей соединения с базой данных или веб-сервисов, а выполняющей вычисление хеш-суммы файла средствами API TESSA. Хеш-сумма вычисляется по тому же алгоритму, по которому платформа вычисляет её для файлов по умолчанию (свойство HashSignatureProvider.Files), в текущей версии системы это алгоритм SHA256.

Добавьте папку с именем GetFileHash в проект Tessa.Extensions.Console, папка будет содержать все файлы для одноимённой команды.

Создайте класс Operation, содержащий действия, выполняемые при вызове команды.

using System; using System.Buffers; using System.Diagnostics; using System.IO; using System.Security.Cryptography; using System.Threading.Tasks; using Tessa.Platform; using Tessa.Platform.ConsoleApps; using Tessa.Platform.IO;

namespace Tessa.Extensions.Console.GetFileHash { public static class Operation { public static async Task<int> ExecuteAsync( IConsoleLogger logger, string filePath) { if (!File.Exists(filePath)) { await logger.ErrorAsync("Can't find file: {0}", filePath); return -1; }

await logger.InfoAsync("Calculating hash for file: {0}", filePath);

var stopwatch = new Stopwatch(); stopwatch.Start();

using HashAlgorithm hashAlgorithm = HashSignatureProvider.Files.CreateAlgorithm(); { const int bufferSize = 1 * 1024 * 1024; // 1 Мб

await using FileStream fileStream = FileHelper.OpenRead(filePath, bufferSize: bufferSize); byte[] buffer = ArrayPool<byte>.Shared.Rent(bufferSize);

int read; while ((read = await fileStream.ReadAsync(buffer, 0, bufferSize)) > 0) { hashAlgorithm.TransformBlock(buffer, 0, read, null, 0); }

hashAlgorithm.TransformFinalBlock(buffer, 0, 0); ArrayPool<byte>.Shared.Return(buffer); }

stopwatch.Stop();

await logger.InfoAsync("Completed in {0:g}", stopwatch.Elapsed); await logger.WriteLineAsync(Convert.ToBase64String(hashAlgorithm.Hash));

return 0; } } }

Создайте класс Command с указанием названия команды, её параметров и их описание для справки.

using System; using System.ComponentModel; using System.IO; using System.Threading.Tasks; using NLog; using Tessa.Localization; using Tessa.Platform.CommandLine; using Tessa.Platform.ConsoleApps;

namespace Tessa.Extensions.Console.GetFileHash { public static class Command { [Verb("GetFileHash")] [Description("Calculates file hash and prints it to console output.")] public static async Task GetFileHash( [Input] TextReader input, [Output] TextWriter stdOut, [Error] TextWriter stdErr, [Argument, Description("Path to a file.")] string filePath, [Argument("q"), LocalizableDescription("Common_CLI_Quiet")] bool quiet = false, [Argument("nologo")] [LocalizableDescription("CLI_NoLogo")] bool nologo = false) { if (string.IsNullOrWhiteSpace(filePath)) { throw new ArgumentException("Please, specify path to a file."); }

if (!nologo && !quiet) { ConsoleAppHelper.WriteLogo(stdOut); }

IConsoleLogger logger = new ConsoleLogger( LogManager.GetLogger(nameof(GetFileHash)), stdOut, stdErr, quiet);

int result = await Operation.ExecuteAsync(logger, filePath); ConsoleAppHelper.EnvironmentExit(result); } } }

Создайте класс CommandRegistrator для регистрации метода команды, приведённого в предыдущем классе. Обратите внимание, что требуется указать типы всех параметров метода Command.GetFileHash в порядке их следования.

using System.IO; using Tessa.Platform.CommandLine; using Tessa.Platform.ConsoleApps;

namespace Tessa.Extensions.Console.GetFileHash { [ConsoleRegistrator] public sealed class CommandRegistrator : ConsoleRegistratorBase { public override void RegisterCommands() { this.CommandContext .AddCommand<TextReader, TextWriter, TextWriter, string, bool, bool>(Command.GetFileHash) ; } } }

Примеры использования команды:

tadmin GetFileHash Tessa.dll

tadmin GetFileHash C:\Files\test.txt -q

Back to top