Как пользоваться утилитой

Требования к работе утилиты:

1. ОС - Windows,
2. .NET Framework 4.8

Термины:

Объект/наносимый объект - тип наносимых данных на pdf-документ. На данный момент - штрихкоды, qr-коды и изображения.

Утилита разделяется на команды:

barcode - команда проставления штрихкодов. Работает только с ASCII-символами (латиница).

qrcode - команда проставления qr-кодов

img - команда проставления изображений

Параметры, общие всем командам:

Флаги (необязательно, тогда простановка объектов будет выполняться в левом верхнем угле):

--std_pos=позиция наносимого объекта в пределах документа (1-левый верхний угол, 2-правый верхний, 3-правый нижний, 4-левый нижний, итого - по часовой стрелке)

--std_poss=перечень позиций, разделенных запятой (например --std_poss=1,3 означает нанести код в левом верхнем и правом нижнем углах документа)

--std_h_off=значение горизонтального смещения при нанесении объекта на документ

--std_v_off=значение вертикального смещения при нанесенни объекта на документ

--std_off_unit=единицы измерения для горизонтального и вертикального смещений. Допустимые единицы - mm (по умолчанию) - миллиметры, cm - сантиметры

Параметры команды barcode:

Флаги (необязательно):

--write_text - должен ли кодируемый текст быть записан под штрихкодом - да, если указан флаг.

Данные, последовательно:

1 - путь к исходному документу (если утилита выполняется в папке с документом, то достаточно указать имя с учётом расширения, например output.pdf)

2 - текст для кодирования (если текст содержит пробелы, то его необходимо заключить в двойные кавычки ")

3 - путь к выходному документу (если требуется сгенерировать документ в папке, где выполняется утилита, достаточно указать имя с учётом расширения, например output.pdf)

Примеры:

pdfstamping barcode --std_pos=2 test.pdf "some text" output.pdf - нанести штрихкод, составленный из текста "some text", на все страницы документа test.pdf в правый верхний угол и сохранить результат в документ output.pdf

pdfstamping barcode --std_poss=1,2 test.pdf "some text" output.pdf - нанести штрихкод, составленный из текста "some text", на все страницы документа test.pdf в левый и правый верхние углы и сохранить результат в документ output.pdf

pdfstamping barcode --std_h_off=13 --std_v_off=6 test.pdf "some text" output.pdf - нанести штрихкод, составленный из текста "some text", с горизонтальным смещением в 13 мм и вертикальным в 6 мм в правый верхний угол и сохранить результат в документ output.pdf

pdfstamping barcode --std_h_off=2 --std_v_off=1 --std_off_unit=cm test.pdf "some text" output.pdf - нанести штрихкод, составленный из текста "some text", с горизонтальным смещением в 2 см и вертикальным в 1 см в левый верхний угол и сохранить результат в документ output.pdf

pdfstamping barcode --std_h_off=2 --std_v_off=1 --std_off_unit=cm test.pdf "some text" output.pdf - нанести штрихкод, составленный из текста "some text", с горизонтальным смещением в 2 см и вертикальным в 1 см в левый верхний угол и сохранить результат в документ output.pdf

pdfstamping barcode --std_h_off=2 --std_v_off=1 --std_off_unit=cm --write_text test.pdf "some text" output.pdf - нанести штрихкод, составленный из текста "some text", с горизонтальным смещением в 2 см и вертикальным в 1 см в левый верхний угол, написать текст под штрихкодом и сохранить результат в документ output.pdf

Параметры команды qrcode:

Флаги (необязательно, для большего контроля над процессом нанесения qr-кода):

--qr_dark_color=color (Цвет темной части qr-кода, где color-наименование цвета в виде red,green,blue и т.д., или шестнадцатиричный rgb-код в виде #FFFFFF, где первые FF-задают степень красного, вторые - зелёного, третьи - синего компонентов цвета)

--qr_light_color=color (Цвет светлой части qr-кода)

-q или --quiet_zone добавляет внутренние отступы к qr-коду

Данные, последовательно:

1 - путь к исходному документу (если утилита выполняется в папке с документом, то достаточно указать имя с учётом расширения, например output.pdf)

2 - текст для кодирования (если текст содержит пробелы, то его необходимо заключить в двойные кавычки ")

3 - путь к выходному документу (если требуется сгенерировать документ в папке, где выполняется утилита, достаточно указать имя с учётом расширения, например output.pdf)

Примеры:

pdfstamping qrcode --std_pos=2 test.pdf -q "some text" output.pdf - нанести qr-код, составленный из текста "some text", с внутренними отступами на все страницы документа test.pdf в правый верхний угол и сохранить результат в документ output.pdf

pdfstamping qrcode --std_poss=1,2 test.pdf "some text" output.pdf - нанести qr-код, составленный из текста "some text", на все страницы документа test.pdf в левый и правый верхние углы и сохранить результат в документ output.pdf

pdfstamping qrcode --qr_dark_color=green --qr_light_color=#34fe4a test.pdf "some text" output.pdf - нанести qr-код, составленный из текста "some text", с фоном rgb-цвета 34fe4a и содержания зелёного цвета, на все страницы документа test.pdf в левый верхний угол и сохранить результат в документ output.pdf

pdfstamping qrcode --std_h_off=13 --std_v_off=6 test.pdf "some text" output.pdf - нанести qr-код, составленный из текста "some text", с горизонтальным смещением в 13 мм и вертикальным в 6 мм в левый верхний угол и сохранить результат в документ output.pdf

pdfstamping qrcode --std_h_off=2 --std_v_off=1 --std_off_unit=cm test.pdf "some text" output.pdf - нанести qr-код, составленный из текста "some text", с горизонтальным смещением в 2 см и вертикальным в 1 см в левый верхний угол и сохранить результат в документ output.pdf

Параметры команды img:

Данные, последовательно:

1 - путь к исходному документу (если утилита выполняется в папке с документом, то достаточно указать имя с учётом расширения, например output.pdf)

2 - путь к изображению (если путь содержит пробелы, то его необходимо заключить в двойные кавычки ")

3 - путь к выходному документу (если требуется сгенерировать документ в папке, где выполняется утилита, достаточно указать имя с учётом расширения, например output.pdf)

Примеры:

pdfstamping img --std_pos=3 test.pdf test.png output.pdf - нанести изображение test.png в нижний левый угол документа test.pdf и сохранить резульат в документ output.pdf

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

Как собрать проект разработчику

Для начала необходимо иметь установленную среду разработки Visual Studio. Разработка утилиты ведётся с использованием последней версии среды. На момент написания этих строк использовалась версия 2022, которая располагается по адресу \\server-file\Users\УИТ\ОИС\programming\C#\Microsoft Visual Studio 2022 Enterprise с readme по установке.

Помимо собственных модулей проект включает также сторонние зависимости в виде nuget-пакетов, которые располагаются в общем репозитории по адресу \\server-file\Users\УИТ\ОИС\programming\C#\NuGetLocalRepository. Поэтому, далее, если это ещё не выполнено, требуется указать в Visual Studio источник nuget-пакетов. Для этого:

1. Через верхнее меню среды кликнуть по пункту Tools -> NuGet Package Manager -> Package Manager Settings. Откроется окно с настройками Visual Studio с позиционированным пунктом Nuget Package Manager.
2. Под данным пунктом выбрать Package Sources, кликнуть по кнопке "+" в правом верхнем углу и заполнить ниже поля Name и Source.
3. Поле Name может быть произвольным на усмотрение. В поле Source нужно указать адрес репозитория, то есть \\server-file\Users\УИТ\ОИС\programming\C#\NuGetLocalRepository.
4. Нажать ОК для сохранения изменений.

Обратите внимание, что пункты выше подразумевают действия, осуществляемые в версии среды не ниже 2022 с английским интерфейсом. В предыдущих версиях шаги по заданию источника nuget-пакетов и их порядок могут отличаться, хотя и маловероятно, в этом отношении Visual Studio поддерживает совместимость.

Далее следует:

1. Открыть данный проект в среде.
2. Visual Studio открывает проекты внутри решений. Если у проекта нет решения, среда создаёт его, но не сохраняет. Для выполнения следующих пунктов необходимо сохранить созданное из проекта решение.
3. Открыть консоль пакетного менеджера также через вернее меню по пути Tools -> NuGet Package Manager -> Package Manager Console.
4. В консоли ввести команду Update-Package -Reinstall. В этой же консоли должны будут со временем появиться сообщения об успешно установленных зависимостях проекта. Появившеюся после выполнения команды папку SharpZipLib можно удалить. Она только содержит readme одной из зависимостей проекта.
5. Собрать проект привычным способом (Ctrl + Shift + B или правой кнопкой по проекту и выбрать Build).