Интеграция Microsoft Dynamics AX Retail POS с ......Интеграция с...

Руководство разработчика

Интеграция Microsoft Dynamics® AX Retail POS с фискальными принтерами

Версия 1.0

Август 2013

Microsoft Dynamics is a line of integrated, adaptable business management solutions that enables you

and your people to make business decisions with greater confidence. Microsoft Dynamics works like and

with familiar Microsoft software, automating and streamlining financial, customer relationship and supply

chain processes in a way that helps you drive business success.

U.S. and Canada Toll Free 1-888-477-7989

Worldwide +1-701-281-6500

www.microsoft.com/dynamics

This document is provided "as-is". Information and views expressed in this document, including URL and other

Internet Web site references, may change without notice. You bear the risk of using it.

Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection

is intended or should be inferred.

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You

may copy and use this document for your internal, reference purposes.

Copyright © 2011 Microsoft . All rights reserved.

Microsoft, Microsoft Dynamics, Excel, SQL Server, and the Microsoft Dynamics Logo are trademarks of the Microsoft

group of companies.

All other trademarks are property of their respective owners.

http://www.microsoft.com/dynamics

Интеграция с фискальными принтерами, руководство разработчика i

Содержание

Введение ......................................................................................................................................... 2

Подключение фискального принтера к Retail POS ...................................................................... 5

Пример интеграции приложения Retail POS с фискальным принтером Штрих-М-ФРК .......... 8

Обзор SDK ..................................................................................................................................... 25

Интеграция приложения Retail POS с новым типом фискального принтера .......................... 27

Обработка ошибок ....................................................................................................................... 29

Добавление обработки операций (BlankOperations) ................................................................ 32

Приложение 1. Пример конфигурационного файла приложения Retail POS ......................... 33

Интеграция с фискальными принтерами, руководство разработчика 2

Введение Данный документ содержит руководство разработчика по интеграции приложения Retail

POS с фискальными принтерами. Для интеграции используется стандартная модель

Extensibilty Framework, основывающаяся на сервисах (Services) и триггерах (Triggers). Более

подробную информацию по кастомизации приложения Retail POS можно получить в

руководстве разработчика Developer’s Guide to Customization, входящем в состав Retail SDK.

Архитектура интеграции приложения Retail POS с фискальными принтерами На схеме изображена архитектура интеграции приложения Retail POS c фискальными

принтерами.

Extensibility Framework

Ядро Интеграция с фискальными принтерами

В рамках модели Extensibility Framework приложение Retail POS взаимодействует с

фискальными принтерами через расширяемые библиотеки сервисов и триггеров. Все

обращения к принтеру выполняются через свойства и методы интерфейса IFiscalPrinter. При

этом будет использован экземпляр одного из классов, реализующих интерфейс

IFiscalPrinter. Загрузка всех классов, реализующих базовый интерфейс, выполняется с

использованием MEF framework в процессе запуска приложения Retail POS. Решение о


хранении и использовании экземпляра одного из них принимается на основе значения,

возвращаемого методом CanBeInitialized, при этом может быть выбран только один класс.

В текущей реализации выбор основывается на коде региона, указанного в настройках

функционального профиля модуля Retail (Поле General \ Locale \ ISO в форме Retail \ Setup \

POS \ Profiles \ Functionality profile). Логика выбора наследника реализована в классе

Peripherals, входящем в состав Retail SDK.

Класс RussianFiscalPrinter содержит реализацию всех свойств и методов интерфейса

IFiscalPrinter, которые вызываются приложением Retail POS. Класс RussianFiscalPrinter

состоит из нескольких C# файлов, в каждом из которых реализована часть методов и свойств

интерфейса IFiscalPrinter, соответствующая одной из функциональных областей: IEOD,

IPrinting и т. д. Области названы в соответствии с сервисами Extensibility Framework, из

которых вызываются данные методы. Внутри методов класса RussianFiscalPrinter

происходит обращение к драйверу фискального принтера через свойства и методы

интерфейса IFiscalPrinterDriver и абстрактного класса RussianFiscalPrinterDriver,

реализующего интерфейс.

В интерфейсе IFiscalPrinterDriver объявлены свойства и методы взаимодействия с

драйвером фискального принтера, общие для всех стран. В классе RussianFiscalPrinterDriver

объявлены дополнительные свойства и методы, вызывающиеся из класса

RussianFiscalPrinter и относящиеся к российской функциональности интеграции с

фискальным принтером. Кроме того, класс RussianFiscalPrinterDriver содержит реализацию

бизнес-логики обработки результатов выполнения операций с фискальным принтером и

обработки исключительных событий. Данная часть методов класса вынесена в отдельный

файл RussianFiscalPrinterDriver.Helpers.cs.

Методы и свойства интерфейса IFiscalPrinterDriver, а также дополнительно объявленные

члены класса RussianFiscalPrinterDriver, должны быть реализованы в наследниках класса

RussianFiscalPrinterDriver. Реализация должна содержать обращения к устройству

фискального принтера через его драйвер. Название класса – наследника

RussianFiscalPrinterDriver, экземпляр которого будет создан для обращения к фискальному

принтеру, должно быть задано в конфигурационном файле приложения Retail POS. На

основе этих настроек в классе FiscalPrinterDriverFactory принимается решение о том,

экземпляр какого класса будет проинициализирован из загруженной сборки (загрузка

также выполняется с использованием MEF framework).

Диаграмма основных классов интеграции с фискальными принтерами:


Данная секция должна быть

скопирована в секцию configSection

файла Pos.exe.config

Подключение фискального принтера к Retail POS

Для того чтобы подключить фискальный принтер к Retail POS необходимо выполнить

следующие действие (пример приведен для фискального регистратора Штрих-М):

1. Установите драйвер фискального регистратора с тестовой утилитой. Версия

драйвера для Штрих-М должна быть не ниже 4.8;

2. Запустите тестовую утилиту и определите/настройте параметры подключения

принтера (COM-порт, таймаут, скорость передачи);

3. Откройте клиент Dynamics AX. В профиле оборудования в разделе «Фискальные

регистраторы» задайте в типе драйвера: Драйвер производителя. Закройте окно

после внесения изменений;

4. Передайте настройки профиля оборудования в Retail POS (Задание N-1090 или A-

1090);

5. Убедитесь, что в конфигурационном файле приложения Retail POS (POS.exe.config)

включены секции, отвечающие за работу с фискальным регистратором. Подробноо

настройке конфигурационного файла приложения вы можете прочитать ниже.

Настройка конфигурационного файла Retail POS (POS.exe.config) Дополнительно для работы с фискальным регистратором необходимо дополнительно

настроить конфигурационный файл приложения POS.exe.config.

1. Зайдите в директорию, в которую был установлен RetailSDK. Далее в папке …\Retail

SDK\POS Plug-ins\FiscalPrinterDrivers\FiscalPrinterDriverFactory вы найдете

конфигурационный файл app.config. Откройте его и скопируйте следующие секции

в POS.exe.config

<?xml version="1.0" encoding="utf-8" ?> <configuration> <configSections> <sectionGroup name="applicationSettings" type="System.Configuration.ApplicationSettingsGroup, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" > <section name="Microsoft.Dynamics.Retail.FiscalPrinter.Properties.Settings" type="System.Configuration.ClientSettingsSection, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" requirePermission="false" /> </sectionGroup> </configSections> <applicationSettings> <Microsoft.Dynamics.Retail.FiscalPrinter.Properties.Settings> <setting name="FiscalPrinterAssembly_HU" serializeAs="String">


Данная секция должна быть скопирована в секцию

applicationSettings файла Pos.exe.config

Данная секция должна быть

скопирована в секцию sectionGroup

файла Pos.exe.config

<value>Microsoft.Dynamics.Retail.FiscalPrinter.PocokPrinter.dll</value> </setting> <setting name="FiscalPrinterClass_HU" serializeAs="String"> <value>Microsoft.Dynamics.Retail.FiscalPrinter.PocokPrinter.Pocok16Printer</value> </setting> <setting name="FiscalPrinterAssembly_BR" serializeAs="String"> <value>Microsoft.Dynamics.Retail.FiscalPrinter.DarumaPrinter.dll</value> </setting> <setting name="FiscalPrinterClass_BR" serializeAs="String"> <value>Microsoft.Dynamics.Retail.FiscalPrinter.DarumaPrinter.DarumaPrinter</value> </setting> <setting name="FiscalPrinterAssembly_RU" serializeAs="String"> <value>Microsoft.Dynamics.Retail.FiscalPrinter.ShtrihPrinter.dll</value> </setting> <setting name="FiscalPrinterClass_RU" serializeAs="String"> <value>Microsoft.Dynamics.Retail.FiscalPrinter.ShtrihPrinter.ShtrihPrinter</value> </setting> </Microsoft.Dynamics.Retail.FiscalPrinter.Properties.Settings> </applicationSettings> </configuration>

2. Откройте app.config в директории …\ Retail SDK\POS Plug-

ins\Services\RussianFiscalPrinter. Откройте его и скопируйте следующие секции в

POS.exe.config

<?xml version="1.0" encoding="utf-8" ?> <configuration> <configSections> <sectionGroup name="applicationSettings" type="System.Configuration.ApplicationSettingsGroup, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" > <section name="Microsoft.Dynamics.Retail.FiscalPrinter.RussianFiscalPrinter.Properties.Settings" type="System.Configuration.ClientSettingsSection, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" requirePermission="false" /> </sectionGroup> </configSections> <applicationSettings> <Microsoft.Dynamics.Retail.FiscalPrinter.RussianFiscalPrinter.Properties.Settings> <setting name="TimeoutStep" serializeAs="String"> <value>100</value> </setting>


Данная секция должна быть скопирована в секцию

applicationSettings файла Pos.exe.config

<setting name="TimeoutDuration" serializeAs="String"> <value>5000</value> </setting> <setting name="SerialConnectionString" serializeAs="String"> <value>COM1:</value> </setting> <setting name="SerialConnectionBaudRate" serializeAs="String"> <value>115200</value> </setting> <setting name="SerialConnectionTimeout" serializeAs="String"> <value>250</value> </setting> <setting name="LogFileName" serializeAs="String"> <value /> </setting> <setting name="ZReportFilePath" serializeAs="String"> <value>.\</value> </setting> <setting name="TimeoutBeforeExit" serializeAs="String"> <value>0</value> </setting> </Microsoft.Dynamics.Retail.FiscalPrinter.RussianFiscalPrinter.Properties.Settings> </applicationSettings> </configuration>

3. После копирования указанных выше секций мы получим конфигурационный файл

POS.exe.config с настройками для работы с фискальным регистратором Штрих-М.

Пример конфигурационного файла вы сможете найти в разделе Приложение 1.


Пример интеграции приложения Retail POS с фискальным принтером Штрих-М-ФРК В Retail SDK в качестве примера реализована интеграция приложения Retail POS c

семейством фискальных принтеров Штрих-М-ФРК. Взаимодействие с драйвером

фискального принтера Штрих-М реализовано в классе ShtrihPrinter – наследнике класса

RussianFiscalPrinterDriver. Дополнительная логика взаимодействия с фискальным

принтером (чтение и обработка настроек внешнего вида документов, заданных в

конфигурационном файле) содержится в остальных классах проекта ShtrihPrinter.

Замечание: Подробную информацию по логике работы фискального принтера Штрих-М и

взаимодействию с его драйвером можно получить в документации, доступной на

официальном сайте производителя принтера.

Список функций, реализованных в данной версии Данная версия поддерживает следующие возможности:

Конфигурирование настроек принтера и дизайна чеков – данная функция

основана на работе с конфигурационным XML-файлом. C его помощью возможна

настройка таблиц принтера и задание дизайна чека для поддерживаемых

документов

Печать основных документов:

o Продажа с оплатой наличными или комбинированным способом o Возврат с оплатой наличными или комбинированным способом o X-отчет o Z-отчет o Внесение наличных (размена) в кассу o Изъятие наличных (выручки) из кассы

Повторная печать последнего чека

Базовая обработка смен - включает в себя открытие смены принтера при

открытии смены в Retail POS и закрытие смены принтера и печать Z-отчета при

закрытии смены в Retail POS. Также контролируется ситуация, когда на принтере

смена открыта более 24 часов, в данном случае выдается предупреждение в

Retail POS.

Обработка налогов

o Настройка сопоставления налоговых групп в Retail POS с налоговыми

группами в принтере. Настройка осуществляется через

конфигурационный файл.

o Корректировка налогов в Retail POS на основании налогов, рассчитанных

принтером.


Обработка способов оплат

o Настройка сопоставления методов оплат в Retail POS с методами оплат в

принтере. Настройка осуществляется через конфигурационный файл.

Печать скидок - Печать скидок по каждой строке или итого по чеку в разбивке по

видам скидки

Печать баллов лояльности - Печать в фискальном чеке информации по

программе лояльности из транзакции (накопленные и/или потраченные баллы и

т.п.)

Просмотр баланса по карте лояльности в Retail POS

o Форма запроса и просмотра данных по карте лояльности в Retail POS (баланс, накопленные и/или потраченные баллы и т.п.);

o Печать отчета по карте лояльности на фискальном принтере.

Сохранение фискальных данных чека в транзакции - Сохранение в Retail POS и

передача в AX базовых данных фискального чека (фискальный номер документа,

номер смены и т.п.). Информация по оборотам не сохраняется из фискальной

памяти принтера в Retail POS.

Список функций, которые планируется добавить в ближайших релизах

Печать чеков для операций по подарочным картам

o Печать фискального чека для продажи подарочной карты (предоплаты); o Печать фискального чека при полной/частичной оплате подарочной картой.

Обработка оплаты баллами лояльности

o Обработка в Retail POS оплаты баллами лояльности как скидки; o Печать в фискальном чеке оплаты баллами лояльности как скидки.

Список функций, не поддерживаемых в данной версии

Печать номера отдела/секции в фискальном чеке

o Ведение номеров отдела/секции по номенклатурам в AX, передача в Retail POS;

o Печать номера отдела/секции в фискальном чеке (в том числе,

конфигурация чека для печати номера отдела/секции).

Работа со штрих-кодом

o Печать на чеке штрих-кода для номера чека (в том числе, конфигурация чека для печати штрих-кода);


o Поиск чека в Retail POS по штрих-коду номера чека.

Обработка заказов клиентов1

o Печать фискального чека для предоплаты по заказу клиента в Retail POS; o Печать фискального чека при окончательной оплате заказа клиента в Retail

POS с учетом ранее внесенных предоплат; o Обработка отмены заказа клиента и печать фискального чека на отмену

предоплаты; o Обработка возвратов по заказам клиентов2.

Дополнительная обработка смен

o Контроль продолжительности смены принтера не более 24 часов при открытии транзакции (помимо стандартной ошибки принтера при печати);

o Ограничение смены принтера одним календарным днем; o Жесткий контроль соответствия смены на принтере и в Retail POS путем

сравнения номера смены для каждой транзакции; o Повторная печать Z-отчета.

Сохранение фискальных данных чека в транзакции - Сохранение данных смены (обороты) из фискальной памяти в Retail POS и в AX.

Централизованное ведение файлов конфигурации принтера

o Ведение файлов конфигурации принтера в AX и распространение конфигурации с использованием Synch service;

o Настройка конфигурационного файла Retail POS для использования

фискального принтера через AX или RetailDatabaseUtility.

Обработка предоплат и оплат по счету клиента

o Печать фискального чека для предоплаты клиента, вносимой на счет клиента (без клиентского заказа);

o Печать фискального чека по продаже с учетом частичной оплаты со счета

клиента.

Печать фискальных чеков для операции доходов/расходов

o Печать фискального чека на операцию дохода (income transaction); o Печать фискального чека на операцию расхода (expense transaction).

1 Для заказов, обрабатываемых через TransactionService

2 Для возвратов заказов, обрабатываемых через TransactionService


Основные составляющие проекта ShtrihPrinter Проект ShtrihPrinter состоит из следующих файлов:

ShtrihPrinter.cs – содержит класс ShtrihPrinter, наследник класса RussianFiscalPrinterDriver. В классе реализовано взаимодействие с драйвером фискального принтера Штрих-М.

ShtrihConstants.cs – содержит класс ShtrihConstants, в котором определены константы, специфичные для устройства фискального принтера Штрих-М.

App.config – файл с конфигурационными настройками фискального принтера.

PrinterConfiguration.cs – содержит набор классов необходимых для загрузки и валидации настроек из конфигурационного файла app.config. В том числе файл содержит класс PrinterConfiguration – наследник системного класса ConfigurationSection, в котором реализована загрузка конфигурационного файла.

PrinterConfigValidator.cs – содержит класс PrinterConfigValidator, в котором реализована валидация загружаемого конфигурационного файла.

PrinterImage.cs – содержит набор классов, реализующих работу фискального принтера Штрих-М с изображениями. Основной класс, являющийся входной точкой для внешних вызовов – класс PrinterImage.

PrinterTable.cs – содержит класс PrinterTableController, реализующий загрузку параметров в настроечные таблицы фискального принтера Штрих-М.

LineManager.cs – содержит класс LineManager, реализующий обработку элементов Line конфигурационного файла. Используется при печати документов с внешним видом, заданным в конфигурационном файле.

FieldManager.cs – содержит класс FieldManager, реализующий обработку элементов Field конфигурационного файла. Используется при печати документов с внешним видом, заданным в конфигурационном файле.

LoyaltyManager.cs – содержит класс LoyaltyManager, реализующий логику расчета баллов лояльности. Используется при печати баллов лояльности.

Структура конфигурационного файла App.config <configuration>, <configSections>, <section> – стандартные секции любого .config

файла, описывают из каких секций он состоит.

<PrinterConfiguration> – корневая секция для принтера

<ImageList> – список изображений используемых в принтере Атрибуты:


default – идентификатор (id) изображения по умолчанию. Если данный атрибут указан, изображение будет загружено сразу при запуске Retail POS. <Image> – описание изображения (логотипа). Атрибуты:

id – уникальный идентификатор path – путь к файлу с изображением (bmp файл размером не более

320x1200) startline – начальная линия (число 1- 1200) endline – конечная линия (число 1- 1200) center – центрировать изображение (true, false)

<Layouts> – список документов, поддерживаемых текущей версией интеграции с фискальным принтером <Layout> – описание документа Атрибуты:

type – тип документа, на данный момент возможны следующие значения:

o Default, по умолчанию o Sale, документ на продажу o Return, документ на возврат o ReportX, X-отчет o ReportZ, Z-отчет o FloatEntry, внесение наличности o TenderRemoval, изъятие денег из кассы o StartAmount, внесение начального остатка o LoyaltyCardBalance, баланс по карте

imageid – идентификатор изображения <DocumentSection> – секция в документе

type – тип секции, на данный момент возможны следующие значения:

o Header, заголовок документа o Footer, подвал документа o SalesLine, секция строк в документе на продажу/возврат o TotalsHeader, над итоговая секция в документе на

продажу/возврат o SimpleSection, основная секция документа, состоящего из

одной секции

<Line> – описывает строку в секции

type – тип строки, на данный момент возможны следующие значения:

o Text, текстовая строка o SalesFiscal, фискальная строка в документе на

продажу/возврат o SalesText, текстовая строка в документе на продажу/возврат


o SummaryDiscount, строка суммарной (по всем типам скидки) скидки

o LineDiscount, строка построчной скидки o PeriodicDicount, строка периодической скидки o ReceiptDiscount, строка общей скидки

hideIfEmptyField – показывает, что строка должная быть скрыта, если поле указанное в атрибуте не заполнено. Принимает те же значения, что и атрибут type тега Field, за исключением Text.

<Field> – описывает поле в строке. Атрибуты:

type – тип поля, на данный момент возможны следующие значения:

o Text, текстовое поле, содержит произвольный текст между открывающим и закрывающим тегами

o Cashier, имя кассира o ReceiptNumber, номер чека o Address, адрес o Customer, имя клиента o TerminalId, номер терминала o StorePhoneNo, телефон магазина o StoreName, наименование магазина o SalesPerson, имя менеджера продаж o ItemNo, код номенклатуры o ItemName, наименование номенклатуры o ItemAlias, краткое наименование номенклатуры o ItemBarcode, штрих-код номенклатуры o UnitOfMeasure, единица измерения номенклатуры o LoyaltyCard, карта лояльности o LoyaltyBalance, баланс карты лояльности o LoyaltyAdded, баллы, начисленные на карту лояльности o LoyaltyUsed, использованные баллы карты лояльности o LoyaltyAmount, сумма оплаты картой лояльности o LoyaltyPercent, процент оплаты картой лояльности o LoyaltyCustomerName, имя клиента карты лояльности o LoyaltyCardStatus, статус карты лояльности o LoyaltyCardType, тип карты лояльности o LoyaltySchemeDescription, описание схемы лояльности o LoyaltyAddedTotal, начислено баллов по карте лояльности

(всего) o LoyaltyUsedTotal, использовано баллов по карте лояльности

(всего) o LoyaltyExpiredTotal, просрочено баллов по карте

лояльности (всего) o SummaryDiscountAmount, сумма суммарной (по всем типам

скидки) скидки o LineDiscountAmount, сумма построчной скидки o PeriodicDicountAmount, сумма периодической скидки


o ReceiptDiscountAmount, сумма общей скидки o SummaryDiscountPercent, процент суммарной (по всем

типам скидок) скидки o LineDiscountPercent, процент построчной скидки o PeriodicDicountPercent, процент периодической скидки o ReceiptDiscountPercent, процент общей скидки o PeriodicDicountName, наименование периодической скидки

length – длина поля в символах. Необязательный параметр. Если текст в поле больше указанной величины, он обрезается. Если меньше, текст дополняется пробелами до указанной длины. Если атрибут alignment="left", то пробелы добавляются в конец строки, если атрибут alignment="right" – в начало.

alignment – выравнивание. Необязательный параметр. Может принимать значения "left" или "right". Если не указан, считается равным “left”.

<RibbonSettings> – секция для настроек отрезания чека Атрибуты:

cutRibbon – показывает, должен ли отрезаться чек. Возможные значения – true, false

partialCut – показывает, должен ли отрезаться чек полностью или частично. Возможные значения – true, false

feedLinesCount – показывает, на сколько прокрутить чек перед его отрезанием.

<Parameter> – позволяет установить параметр (поле таблицы) в фискальный принтер. Между открывающим и закрывающим тегом должно находится значение, устанавливаемое в принтер. Атрибуты:

tableId – номер таблицы принтера

rowId - номер строки таблицы принтера fieldId - номер поля в строке таблицы

type - тип поля, возможные значения “integer” и “string” <TaxMapping> – элемент для установки соответствия между налоговыми кодами AX и принтера, состоит из списка элементов <Tax>. Должен содержать хотя бы 1 элемент.

<Tax> – элемент устанавливает соответствие между налоговым кодом AX и принтера. Атрибуты:

taxCode – Налоговый код AX; printerTaxId – Налоговый код принтера

<TenderTypesMapping> – элемент для установки соответствия между видами платежей AX и принтера, состоит из списка элементов <TenderType>. Должен содержать хотя бы 1 элемент.

<TenderType> – элемент устанавливает соответствие между видом платежа AX и принтера. Атрибуты:

tenderTypeId – Вид платежа AX printerPaymentType – Вид платежа фискального принтера


Рекомендация по настройке рекламного текста

В фискальном регистраторе Штрих-М есть возможность задать рекламный текст в

таблице №4, который будет выводится в конце документа. В связи с особенностью

обработки состояний принтера в определенных ситуациях может возникнуть критическая

ошибка. Данная ошибка связана с тем, что после окончания печати основной части

документа и вывода на печать фискальной информации и рекламного текста, при опросе

состояния принтер вернет ответ, что он готов к печати. Следовательно при вызове команды

фискального регистратора произойдет исключительная ситуация.

Для предотвращения подобных ошибок мы рекомендуем использовать специальную

секцию документа Footer, которая также позволит вывести рекламный текст.

Примеры последовательностей действий при операциях с фискальными принтерами

Инициализация принтера

Входной точкой вызова инициализации фискального принтера является метод

InitializePrinter интерфейса IFiscalPrinter. Данный метод реализован в классе

RussianFiscalPrinter в виде вызова метода Initialize интерфейса IFiscalPrinterDriver. В метод

передаются настройки порта, скорости соединения, таймаута подключения и лог файла,

указанные в конфигурационном файле приложения. Метод Initialize реализован в классе

ShtrihPrinter. В методе выполняется:

Проверка корректности входных параметров метода;

Загрузка конфигурационного файла библиотеки ShtrihPrinter вызовом метода

GetConfig класса PrinterConfiguration;

Установка параметров подключения экземпляра драйвера принтера _driver через

его свойства ComNumber, BaudRate, ConnectionTimeout, Password, ComLogFile;

Вызов метода драйвера Connect с целью инициализации подключения к устройству

фискального принтера;

Обработка результата подключения и исключительных событий в методе

CheckResultCode класса RussianFiscalPrinterDriver;

Отмена открытого чека вызовом метода CancelReceipt;

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

SetPrinterDefaultParameters класса PrinterTableController;

Загрузка изображения в устройство фискального принтера в методе

SetPrinterDefaultParameters класса PrinterImageController.


Печать чека

Входной точкой печати чека на фискальном принтере является метод PreEndTransaction

интерфейса IFiscalPrinter. Для вызова данного метода в приложении Retail POS использован

стандартный механизм триггеров (Triggers) Extensibilty Framework: в классе

TransactionTriggers, входящем в библиотеку FiscalPrinterTriggers реализован метод-триггер

PreEndTransaction, вызывающийся ядром приложения перед завершением транзакции. В

данном методе происходит вызов одноименного метода PreEndTransaction интерфейса

IFiscalPrinter. Замечание: Совпадение наименования метода интерфейса IFiscalPrinter с

наименованием метода-триггера не является обязательным требованием. Метод

PreEndTransaction интерфейса IFiscalPrinter реализован в классе RussianFiscalPrinter

следующим образом:

Выполняется проверка корректности входных параметров метода

Выполняется проверка статуса транзакции: обрабатываются только транзакции со

статусом Normal

Вызывается класс TriggerFactory, который создает для транзакции с типом

RetailTransaction экземпляр класса PreEndRetailTransactionTrigger. Данный класс

реализует стандартный интерфейс ITrigger, то есть является “приватным” триггером

события PreEndTransaction.

У созданного экземпляра класса “приватного” триггера

PreEndRetailTransactionTrigger вызываются метод PreExecute. В данный метод

триггера добавлен вызов расчета баллов лояльности для возможности их печати в

чеке. Для расчета баллов вызывается метод CalculateLoyaltyPoints службы Loyalty,

входящей в состав Extensibility Framework.

Вызывается метод проверки готовности принтера к печати IsPrinterReady. Метод

реализован в этом же классе RussianFiscalPrinter: выполняется вызов одноименного

метода IsPrinterReady интерфейса IFiscalPrinterDriver. Данный метод реализован в

классе ShtrihPrinter – наследнике RussianFiscalPrinterDriver.

В случае если принтер не готов к печати чека, в классе “приватного” триггера

PreEndRetailTransactionTrigger вызывается метод Abort. В данном методе

выполнется отмена чека путем вызова метода CancelReceipt интерфейса

IFiscalPrinterDriver.

В случае если принтер готов к печати, вызывается метод Execute класса “приватного”

триггера PreEndRetailTransactionTrigger. В данном методе вызывается приватный

метод PrintFiscalDocument класса RussianFiscalPrinter.

Приватный метод PrintFiscalDocument содержит высокоуровневую логику печати

фискального чека и работает следующим образом:

Вызывается приватный метод BeginFiscalDocument, в котором определяется тип

чека: FiscalReceipt (продажа) или RegularRefund (возврат) и вызывается метод


BeginReceipt интерфейса IFiscalPrinterDriver. Данный метод реализован в классе

ShtrihPrinter – наследнике RussianFiscalPrinterDriver. В методе выполняется:

o Проверка корректности входных параметров метода;

o Отмена открытого чека вызовом метода CancelReceipt;

o Установка типа чека через свойство CheckType экземпляра драйвера

принтера _driver в методе InitCheckTypeFromReceiptType;

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

SetPrinterParameters;

o Открытие чека на фискальном принтере вызовом метода OpenCheck

экземпляра драйвера принтера _driver. Для обработки исключительных

событий вызов метода OpenCheck заключен в метод обработки операций

печати ExecutePrintingOperation;

o Печать заголовка чека вызовом метода PrintDocumentHeader.

Для каждой строки транзакции (элемент коллекции retailTransaction.SaleItems)

вызывается приватный метод печати строки PrintLine, в котором вызывается метод

AddItem интерфейса IFiscalPrinterDriver. В качестве параметров в метод передается

тип чека, печатаемая строка SalesLineItem и набор используемых налоговых кодов

фискального принтера в виде строки, разделенной пробелами. Метод AddItem, в

свою очередь, реализован в классе ShtrihPrinter следующим образом:

o Создается экземпляр класса менеджера строк внешнего вида чека

LineManager;

o Из конфигурационных настроек считывается коллекция печатаемых строк

для соответствующего типа документа (продажа/возврат) вызовом метода

GetLineCollection менеджера строк;

o Каждая из печатаемых строк выводится на принтер вызовами методов

PrintFiscalLine (печать фискальной строки), PrintSalesDiscountLine (печать

строки скидки) и PrintTextString (печать текстовой строки) в зависимости от

типа строки;

o В случае если в конфигурационном файле не было задано ни одной строки с

типом SalesFiscal (фискальная строка), она печатается принудительно в

конце метода AddItem. Внутри метода печати фискальной строки

выполняется набор обращений к свойствам и методам экземляра драйвера

принтера _driver, необходимых для регистрации строки продажи/возврата в

фискальном принтере:

В свойстве StringForPrinting задается текст строки, в свойстве Price –

цена из строки lineItem.Price, в свойстве Quantity – количество по

строке lineItem.Quantity.


Налоговые региcтры Tax1..Tax4 обнуляются и устаналиваются в

соответствии с переданным в метод параметром taxRateId,

содержащим набор налоговых кодов фискального принтера.

В зависимости от типа операции (продажа/возврат) вызывается

метод драйвера Sale или метод ReturnSale, регистрирующие строку в

фискальном принтере. Для обработки исключительных событий

вызов данных методов заключен в метод обработки операций

печати ExecutePrintingOperation.

После печати строк транзакции вызывается приватный метод PrintTotalsHeader

класса RussianFiscalPrinter, в котором выполняется печать надитоговой секции чека.

В методе вызывается одноименный метод PrintTotalsHeader класса

RussianFiscalPrinterDriver. Данный метод реализован в классе ShtrihPrinter ‒ в

методе происходит вызов метод печати секции документа PrintDocumentTextLines с

типом секции DocumentSectionType.TotalsHeader.

После печати надитоговой секции чека вызывается статический метод

DistributeTaxFromTotalsHeaderDiscounts класса DiscountHelper. В нем выполняется

корректировка сумм налогов в строках заказа на суммы налогов, рассчитанные по

скидкам в надитоговой секции чека.

После корректировки налогов вызывается приватный метод ValidateTotalAmount

класса RussianFiscalPrinter, проверяющий соответствие итоговой суммы транзакции

в Retail POS итоговой сумме открытого чека в фискальном принтере.

Далее выполняется приватный метод PrintTenderLines, в котором происходит

регистрация сумм и способов оплаты в фискальном принтере. В данном методе:

o Вызывается метод StartTotalPayment класса RussianFiscalPrinterDriver.

Данный метод реализован в классе ShtrihPrinter: в методе обнуляются

регистры сумм Summ1..Summ4 экземпляра драйвера принтера _driver.

o Выполняются количественные проверки сумм оплат и проверки на

соответствие способов оплаты конфигурационным настройкам.

o Суммы оплат группируются по способам оплаты фискального принтера в

экземпляре словаря paymentMethodAmounts.

o Для каждого способа оплаты из словаря paymentMethodAmounts

вызывается метод AddPayment интерфейса IFiscalPrinterDriver. Данный

метод реализован в классе ShtrihPrinter: регистры сумм Summ1..Summ4

экземпляра драйвера принтера _driver инициализируются значениями сумм

из словаря paymentMethodAmounts.

Завершает метод PrintFiscalDocument вызов приватного метода EndFiscalDocument.

В данном методе определяется тип чека и вызывается метод EndReceipt интерфейса

IFiscalPrinterDriver. Данный метод реализован в классе ShtrihPrinter – наследнике

RussianFiscalPrinterDriver. В методе выполняется:


o Проверка корректности входных параметров метода;

o Закрытие чека на фискальном принтере вызовом метода CloseCheck

экземпляра драйвера принтера _driver. Для обработки исключительных

событий вызов метода CloseCheck заключен в метод обработки операций

печати CheckResultCode;

o Печать нижнего колонтитула чека вызовом метода PrintDocumentFooter.

Закрытие смены на принтере, печать Z-отчета

Бизнес-логика закрытия смены в приложении Retail POS реализована в сервисе EOD. В

данный сервис в методе CloseShift добавлен вызов метода PrintZReport интерфейса

IFiscalPrinter для случая, если в настройках фукционального профиля модуля Retail указан

код страны RU. Метод PrintZReport интерфейса IFiscalPrinter является входной точкой

вызова закрытия смены на принтере. Данный метод реализован в классе RussianFiscalPrinter

в виде вызова метода GenerateZReportAndFiles интерфейса IFiscalPrinterDriver с

предварительным выводом диалогового окна подтверждения печати Z-отчета. Метод

GenerateZReportAndFiles реализован в классе ShtrihPrinter. В методе выполняется:

Отмена открытого чека вызовом метода CancelReceipt;

Проверка открытой смены на фискальном принтере в методе IsDayOpened;

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


Печать заголовка Z-отчета в методе PrintDocumentHeader;

Вызов метода драйвера PrintReportWithCleaning для закрытия смены с печатью Z-

отчета на фискальном принтере;

Обработка результата закрытия смены и исключительных событий в методе

CheckResultCode класса RussianFiscalPrinterDriver. В этом же методе происходит

установка свойства PrintingReportCommandSuccessfullySent – признака успешного

завершения операции печати отчета;

Печать нижнего колонтитула Z-отчета в методе PrintDocumentFooter.

В случае возникновения исключительной ситуации при выполнении метода PrintZReport в

методе CloseShift сервиса EOD анализируется состояние флага

PrintingReportCommandSuccessfullySent класса RussianFiscalPrinterDriver. Установленный

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

случае необходимо продолжить закрытие смены в приложении Retail POS в штатном

режиме. В противном случае происходит отмена закрытия смены в приложении путем

обнуления переменной batch. Эта логика обусловлена особенностью работы фискального

принтера Штрих-М.


Печать начального остатка

Для реализации данного функционала в стандартный Retail SDK были внесены следующие

изменения:

В классе RussianFiscalPrinterDriver объявлен новый абстрактный метод

PrintStartingAmount с двумя параметрами: суммой начального остатка total и

текстовым комментарием message.

В интерфейсе IFiscalPrinter добавлен новый public метод PrintStartingAmount.

Данный метод является входной точкой вызова печати начального остатка на

фискальном принтере. Замечание: совпадение названий методов в интерфейсе

IFiscalPrinter и классе RussianFiscalPrinterDriver не является обязательным

требованием. В методе выполняется преобразование входящего параметра –

транзакции posTransaction к типу StartingAmountTransaction. Если преобразование

выполнено успешно, то вызывается метод PrintStartingAmount класса

RussianFiscalPrinterDriver. Сумма начального остатка и комментарий передаются из

транзакции startingAmountDeclaration в метод в качестве параметров.

В классе ShtrihPrinter содержится реализация метода PrintStartingAmount,

объявленного в родительском классе RussianFiscalPrinterDriver. В методе

выполняются:

o Инициализация суммового регистра Summ1 экземпляра драйвера

фискального принтера _driver;

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


o Печать заголовка начального остатка в методе PrintDocumentHeader;

o Вызов метода драйвера CashIncome для регистрации и печати внесения

начального остатка на фискальном принтере. Для обработки

исключительных событий вызов метода CashIncome заключен в метод

обработки операций печати CheckResultCode;

o Печать нижнего колонтитула начального остатка в методе

PrintDocumentFooter.

Для подключения созданного выше функционала печати начального остатка к

стандартной операции объявления начального остатка был модифицирован сервис

Printing: в стандартный метод PrintStartngAmountReceipt добавлен вызов метода

PrintStartingAmount интерфейса IFiscalPrinter.

Сохранение фискальной информации в базе данных

По завершении транзакции Retail POS выполняется ее сохранение в базу данных, таблица

RetailTransactionTable. Первоначально фискальные данные собираются до выполнения


фискальной операции на принтере, вызовом приватного метода FillFiscalMemoryData

определенного в ShtrihPrinter. Сделано это для корректной обработки тех случаев, когда

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

завершения печати и закрытия транзакции. При заполнении поля OpenDocumentNumber в

качестве его значения берется номер следующего фискального документа. Поле KPKNumber

не заполняется. В процессе сохранения данных транзакции срабатывает триггер

SaveTransaction, в котором реализован вызов метода SaveTransaction интерфейса

IFiscalPrinter. В классе RussianFiscalPrinter реализация метода SaveTransaction содержит

следующие шаги:

Получение данных из памяти фискального принтера – метод

RetrieveFiscalMemoryData абстрактного класса RussianFiscalPrinterDriver. Данный

метод реализован в классе ShtrihPrinter и, в случае наличия соединения с

принтером, выполняет повторное считывание в структуру данных FiscalMemoryData,

обновляя значения следующих полей драйвера принтера:

o SessionNumber

o LastKPKNumber

o EKLZNumber

o SerialNumber

o OpenDocumentNumber

Сохранение полученной информации в таблицу RetailTransactionTable_RU базы

данных Retail POS – метод Save класса TransactionFiscalData

В случае если на этапе сохранения транзакции принтер недоступен, используются

значения считанные до выполнения фискальной операции на принтере. Таким образом,

запись фискальной информации в базу данных Retail POS выполняется в любом случае,

если фискальная операция была успешно отправлена на принтер, даже в случае если на

финальной стадии операции или после ее выполнения, но до закрытия транзакции в Retail

POS связь с принтером была потеряна.

Пустое поле KPKNumber в таблице фискальных данных сигнализирует о том, что связь с

принтером была потеряна после отправки операции на принтер, но до момента закрытия

транзакции в Retail POS.

Описанные шаги выполняются для следующих типов транзакций Retail POS:

LogOn – вход в Retail POS, при условии открытия смены на фискальном принтере

CloseShift – закрытие смены

Sales – операции продажи и возврата

StartingAmount – ввод начального остатка

FloatEntry – внесение наличности в кассу


RemoveTender – изъятие наличности из кассы

Ошибки и исключительные ситуации, возникающие в результате выполнения этих

операций, не блокируют завершение транзакции Retail POS, но записываются в лог.

Таким образом, реализовано сохранение данных, генерируемых при регистрации

фискальных операций на принтере.

Из базы данных Retail POS фискальная информация может быть передана в одноименную

таблицу базы Dynamics AX с помощью расширенной настройки задачи P-0001. Расширенная

настройка задачи выполняется при вызове метода Run класса

RetailConnSeedDataGenerator_RU. Переданная фискальная информация может быть

просмотрена в соответствующих полях формы RetailTransactionTable в приложении

Dynamics AX.


Пример добавления поддержки нового типа поля в конфигурационный файл

Рассмотрим случай, когда перед нами стоит задача добавления нового поля в

конфигурационный файл, которое отвечало бы за вывод цвета товара. Для этого нам

необходимо выполнить следующую последовательность действий:

Добавить новое поле в справочник полей (PrinterConfiguration.cs)

Добавить логику заполнения данного поля (LineManager.cs)

Ниже рассмотрим данные шаги более подробно.

Добавление нового поля в справочник полей

Согласно требованиям, изложенным выше, добавим поле с названием ItemColorName.

Для этого необходимо выполнить следующие действия:

Открыть проект в ShtrihPrinter, который находится в RetailSDK в следующей

директории: ($INETROOT)\ Retail SDK\POS Plug-

ins\FiscalPrinterDrivers\ShtrihPrinter

Открыть файл PrinterConfiguration.cs и перейти к перечислению FieldType

Добавим новое поле ItemColorName в список, наложив ограничения на секции документа, где он может быть использован, и указав, что это поле является параметром. Так как это поле может быть использованное только в чеках на продажу и возврат, оно будет выводится только в следующих секциях документа: SalesText и SalesFiscal: [FieldCategory(FieldCategory.Parameter)]

[LineTypeAllowed(LineType.SalesFiscal, LineType.SalesText)] ItemColorName,


В итоге FieldType enum будет выглядеть следующим образом:

Добавление логики заполнения поля

Перейдем в проекте ShtrihPrinter к классу LineManager. Данное поле будет обновляться

при печати каждой строки номенклатуры, поэтому перейдем в метод: private void

PopulateLineDictionaryForSale(LSRetailPosis.Transaction.Line.SaleItem.SaleLineItem

lineItem)

В данном методе нам нужно добавить логику заполнения нашего поля. Цвет мы можем

получить из свойства ColorName. В итоге мы получим следующую логику заполнения поля:

lineDictionary[FieldType.ItemColorName] = lineItem != null ?

lineItem.Dimension.ColorName : string.Empty;

В итоге код будет выглядеть следующим образом:

Компиляция и изменение конфигурационного файла

Скомпилируйте проект согласно инструкциям из раздела, посвященного компиляции

проектов интеграции фискальных принтеров.


Обзор SDK

Решение интеграции с фискальными принтерами состоит из 6 проектов, которые

находятся в следующих папках:

RetailSDK\POS Plugi-ins\FiscalPrinterDrivers:

o FiscalPrinterDriver – проект содержит общий интерфейс для фискальных

принтеров.

o FiscalPrinterDriverFactory – проект отвечает за инициализацию конкретного

экземпляра класса, ответственного за работу с определенным драйвером

принтера.

o ShtrihPrinter – проект содержит реализацию интерфейса фискального

принтера и отвечает за взаимодействие с драйвером принтера Штрих-М.

RetailSDK\POS Plugi-ins\Services:

o FiscalPrinterUtilities – содержит набор классов реализующие общие методы

необходимые для работы с фискальными принтерами, расширение базовых

классов (например RetailTransation).

o RussianFiscalPrinter – содержит общие методы для российских фискальных

принтеров.

RetailSDK\POS Plugi-ins\Triggers: FiscalPrinterTriggers – проект отвечает за вызов

методов фискального принтера при срабатывании соответствующих триггеров.

Компиляция проектов Так как проекты ссылаются друг на друга не только по имени, но и по ключу

(publicToken), при изменении одного из проектов, необходимо будет перекомпилировать

все проекты в определенной последовательности:

Для начала нужно из директории приложения Retail POS\Services необходимо

удалить Microsoft.Dynamics.Retail.FiscalPrinter.BrazilianFiscalPrinter.dll и

Microsoft.Dynamics.Retail.FiscalPrinter.HungarianFiscalPrinter.dll. Это связано с тем

что эти библиотеки ссылаются на общие проекты, такие как: FiscalPrinterDriver,

FiscalPrinterDriverFactory и FiscalPrinterUtilities, которые изменят свой ключ после

компиляции. Из-за этого невозможно будет загрузить указанные в начале

библиотеки, что приведет к ошибке вовремя загрузки приложения.

Удалите из директории приложения Retail POS\FiscalPrinterDrivers следующие

библиотеки: Microsoft.Dynamics.Retail.FiscalPrinter.BematechPrinter.dll,

Microsoft.Dynamics.Retail.FiscalPrinter.PocokPrinter.dll,

Microsoft.Dynamics.Retail.FiscalPrinter.DarumaPrinter.dll


Скомпилируйте проект FiscalPrinterUtilities и скопируйте полученную библиотеку

Microsoft.Dynamics.Retail.FiscalPrinter.FiscalPrinterUtilities.dll в директорию с Retail

POS в папку Services, заменив таким образом существующую библиотеку

Далее скомпилируйте проект FiscalPrinterDriver и скопируйте полученную

библиотеку Microsoft.Dynamics.Retail.FiscalPrinter.FiscalPrinterDriver.dll в

директорию с Retail POS в папку Services, заменив таким образом существующую

библиотеку

На следующем этапе необходимо скомпилировать проект

FiscalPrinterDriverFactory и FiscalPrinterTriggers. Полученные библиотеки нужно

скопировать в соответствующие папки приложения Retail POS, заменив уже

существующие версии библиотек.

Microsoft.Dynamics.Retail.FiscalPrinter.FiscalPrinterDriverFactory должна быть

скопирована в папку Services, а

Microsoft.Dynamics.Retail.FiscalPrinter.FiscalPrinterTriggers в директории Triggers

Скомпилируйте проект RussianFiscalPrinter и полученную библиотеку

Microsoft.Dynamics.Retail.FiscalPrinter.RussianFiscalPrinter.dll в директорию Services

приложения Retail POS, заменив существующую библиотеку.

На последнем шаге необходимо скомпилировать проект ShtrihPrinter и

скопировать полученную библиотеку

Microsoft.Dynamics.Retail.FiscalPrinter.ShtrihPrinter.dll в папку FiscalPrinterDrivers

приложения Retail POS.


Интеграция приложения Retail POS с новым типом фискального принтера В данной главе приведена рекомендуемая последовательность действий для реализации

интеграции приложения Retail POS c новым типом фискального принтера.

Создание нового проекта в Retail SDK Откройте решение Retail SDK.

Создайте новый Class library проект.

Назовите проект.

В свойствах проекта задайте наименование сборки и пространство имен. Например,

Microsoft.Dynamics.Retail.FiscalPrinter.MyPrinter.

В Solution Explorer перейдите на закладку References созданного проекта.

Добавьте в проект ссылки на проекты Retail SDK FiscalPrinterDriver и

RussianFiscalPrinter

Добавление драйвера фискального принтера в проект

В Solution Explorer перейдите на закладку References созданного проекта.

Вызовите пункт меню Add reference.

Найдите библиотеку драйвера фискального принтера и добавьте в проект.

Замечание: В случае если драйвер принтера реализован не в виде COM или .Net

библиотеки, обратитесь к производителю драйвера для уточнения порядка использования

драйвера из MS .Net приложений.

Создание наследника класса RussianFiscalPrinterDriver

В Solution Explorer перейдите на созданный проект.

Создайте новый C# класс.

Задайте имя класса и пространство имен, например MyPrinter и

Microsoft.Dynamics.Retail.FiscalPrinter.MyPrinter

Укажите класс RussianFiscalPrinterDriver в качестве родителя созданного класса.

Реализуйте все необходимые методы интерфейса IFiscalPrinterDriver и класса

RussianFiscalPrinterDriver в созданном классе.


Подключение созданной сборки к приложению Retail POS

Скомпилируйте и соберите созданный проект.

Скопируйте собранную сборку из папки Output, указанной в свойствах проекта, в

папку FiscalPrinterDrivers приложения Retail POS.

Добавьте настройки с названиями сборки и класса в узел

<Microsoft.Dynamics.Retail.FiscalPrinter.Properties.Settings> конфигурационного

файла POS.exe.config приложения Retail POS. В значениях элементов value

необходимо указать полное название сборки и полное название класса. Например:

<setting name="FiscalPrinterAssembly_RU" serializeAs="String">

<value>Microsoft.Dynamics.Retail.FiscalPrinter.MyPrinter.dll</value>

</setting>

<setting name="FiscalPrinterClass_RU" serializeAs="String">

<value>Microsoft.Dynamics.Retail.FiscalPrinter.MyPrinter.MyPrinter</value>

</setting>

Запустите приложение Retail POS и проверьте работу созданной сборки.


Обработка ошибок

Взаимодействие с драйвером Все обращения к драйверу происходят посредством методов помощников класса

RussianFiscalPrinterDriver: CheckResultCode и ExecutePrintingOperation.

Взаимодействие с методами драйвера построено через делегат PrinterMethod,

объявленный в классе RussianFiscalPrinterDriver.

public delegate int PrinterMethod()

Это удобный формат взаимодействия с методами драйвера, который позволяет нам

работать с ними в унифицированном стиле, получая на выходе код ошибки в один вызов.

Вызов каждой драйверной операции производится с использованием метода помощника

CheckResultCode.

Метод ExecutePrintingOperation используется для вызова операций, связанных с печатью

на принтере. Внутри себя он вызывает метод CheckResultCode, а также выполняет

некоторую дополнительную работу до и после вызова основного метода.

В частности, метод ExecutePrintingOperation выполняет проверку готовности принтера к

печати и ожидание успешного завершения печати, производит координацию

управляющих флагов состояния класса контроллера драйвера принтера, а также

отслеживает признак того, что принтер получил команду печати (в частности, это

используется для контроля синхронизации закрытия смены на принтере и в Retail POS).

Общая логика обработки ошибок драйвера Общая логика обработки ошибок предполагает следующую последовательность действий:

1. Проверку состояния готовности к печати (для команд печати)

2. Вызов операции драйвера

3. Анализ кода ошибки

4. Проверку состояния печати (для команд печати)

Прежде всего, интерес представляет проверка состояния печати и анализ кода ошибки.

Анализ кода ошибки

Каждая команда драйвера возвращает код ошибки, который говорит о том, успешно ли

прошла команда.

В случае если код ошибки отличается от кода успешного выполнения, производится

попытка диагностировать ошибку на основании запроса и анализа дополнительных флагов


состояний или на основании соответствия кода ошибки одной из известных категорий

ошибок (например, отсутствие соединения с принтером).

Генерация исключения в случае ошибки драйвера

В случае если никакой специализированной обработки для данной ошибки не

предусмотрено, генерируется исключение типа FiscalPrinterException, с текстом сообщения

об ошибке, передаваемого драйвером.

Генерация данного исключения производится посредством вызова метода ThrowException

класса помощника ExceptionHelper.

При генерации исключения таким способом сообщение с текстом исключения сначала

отображается в диалоге об ошибке в пользовательском интерфейсе (если явно не указано,

что не нужно отображать диалог пользователю в перегрузке метода ThrowException),

регистрируется в журнале событий приложения, а затем исключение прокидывается вверх

по стеку вызовов и обрабатывается там набором обработчиков исключений Core POS &

Extensibility Framework.

Область видимости FiscalPrinterException ограничивается Extensibility Framework (т.е.

областью Triggers & Services), а значит, специализированная обработка данного вида

исключения возможна только в указанных пределах. Выше по стеку (в области Core POS)

исключение может быть обработано либо как PosisException, либо как базовое

исключение (Exception).

Генерация исключения в такой манере безопасна и приводит к прерыванию цепочки

выполнения в рамках текущей операции Retail POS. После отображения диалога с

сообщением об ошибке система будет готова к запуску новой операции или повторному

запуску той же самой операции, и вся обработка пойдет заново.

Обработка ошибок печати

Тип операции определяется перечислимым типом PrinterOperationType, который

передается в качестве параметра методам CheckResultCode и ExecutePrintingOperation.

В случае если операция считается операцией печати, перед запуском операции

выполняется проверка готовности принтера к печати посредством вызова приватного

метода CheckPrinterIsReadyForPrinting.

Метод CheckPrinterIsReadyForPrinting анализирует подрежимы печати и выполняет

необходимые действия. В частности, он выдает диалог Retry/Cancel, если возникла

проблема с бумагой (отсутствие или обрыв бумаги на принтере), и пытается повторить

операцию или отметить ее выполнение. Кроме того, данный метод автоматически

обрабатывает ситуацию ожидания возобновления печати на принтере, подавая

соответствующую команду на принтер.

Обработка ошибок печати фискального чека возможна перепечатыванием того же самого

чека без отмены операции, поэтому при возникновении ошибок печати во время печати

чека, чек просто перепечатывается заново по кнопке Retry. Такое же перепечатывание

допустимо и для встроенных в принтер отчетов X и Z.


Обработка ошибок печати при печати нефискальных документов (в частности банковских

слипов) устроена несколько иначе.

Ввиду того, что слип является нефискальным документом и печатается просто как набор

строк, драйвер не в состоянии отследить границы начала и окончания слипа и потому

нуждается в некоторой внешней координации для перепечатывания целиком. Такая

внешняя координация обеспечивается посредством флага

RussianFiscalPrinter.IsPrintingSlipDocument.

Данный флаг позволяет определять состояние печати составного документа (слипа) на

уровне драйвера и пробрасывать исключения вверх по стеку вызовов, зная о том, что они

будут обработаны механизмом печати слипов, который выдает свое диалоговое окно

Retry/Cancel и обеспечивает повторный запуск печати слипа с начала по кнопке Retry.

Отсутствие соединения с принтером

С целью исключить повторяющиеся сообщения об ошибках про отсутствие соединения с

принтером при печати чека был введен дополнительный флаг IsNotConnected в классе

RussianFiscalprinterDfriver. Данный флаг выставляется в случае, если код ошибки совпадает

с одним из кодов ошибок, классифицируемых как отсутствие соединения. В случае если

произошла ошибка, связанная с отсутствием соединения с принтером, и флаг уже

выставлен, то пользователю не выдается повторного сообщения с той же ошибкой, но

исключение все равно генерируется.

Перед началом каждой печатной операции управляющие флаги принтера сбрасываются,

так что каждая новая операция проходит свой цикл выполнения и обработки ошибок,

независимо от результатов выполнения предыдущей операции.

Повторяющиеся сообщения об ошибке

Нетрудно заметить, что в ряде случаев сообщение об одной и той же ошибке выдается

несколько раз подряд (в разных окошках). Причина такого поведения кроется в

организации обработчиков исключений для разных операций Retail POS.

Разные операции Retail POS имеют разный путь выполнения, тем не менее, вызов

принтера всегда происходит посредством Extensibility Framework (Services & Triggers).

При генерации исключения первым срабатывает обработчик в Services & Triggers (если не

определено локального обработчика исключения по месту вызова команды принтера).

Текст сообщения об ошибке выдается пользователю, регистрируется в журнале событий

приложения, а затем прокидывается вверх по стеку вызова. Следующий обработчик

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

форме PosisException) и прокидывает исключение еще выше. В результате, в некоторых

случаях мы имеем два одинаковых сообщения об ошибке, выдаваемых последовательно в

форме разных диалогов, а также завершающего сообщения с описанием ошибки,

произошедшей в Core POS. Данное поведение является проектным решением архитектуры

Core POS (i.e. By Design) и не модифицировалось в рамках локализации решения для Retail.


Добавление обработки операций (BlankOperations)

Работа с объектами, реализующими интерфейс IBlankOperations, отличается от работы с

объектами, унаследованными от интерфейса IService. При загрузке приложения Retail POS

будут загружены все объекты, реализующие интерфейс IBlankOperations, в этом и

заключается основное отличие от работы с другими интерфейсами, где может быть

импортирован только один объект. При вызове операции будет вызван метод void BlankOperation(IBlankOperationInfo operationInfo, IPosTransaction posTransaction);

у всех загруженных объектов, реализующих данный интерфейс.

Таким образом можно реализовывать метод интерфейс IBlankOperations в отдельном

вашем сервисе или классе.

Метод BlankOperion фискального принтера вызывается в сервисе BlankOperations. Если

вам необходимо добавить обработку операций на уровне фискального принтера, ее

необходимо реализовать в RussianFiscalPrinter в BlankOperation. Для обработки прочих

операций, не относящихся к фискальным принтерам, вы можете как модифицировать

метод BlankOperation сервиса BlankOperations, так и создать свой собственный класс,

реализующий интерфейс IBlankOperions, на примере реализации класса BlankOperations.

Приложение 1. Пример конфигурационного файла приложения Retail POS

<?xml version="1.0" encoding="utf-8" ?> <configuration> <configSections> <section name="AxRetailPOS" type="LSRetailPosis.Settings.ConfigFile.AppConfiguration, SystemSettings, Version=6.2.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" /> <sectionGroup name="applicationSettings" type="System.Configuration.ApplicationSettingsGroup, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"> <section name="Microsoft.Dynamics.Retail.FiscalPrinter.Properties.Settings" type="System.Configuration.ClientSettingsSection, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" requirePermission="false"/> <section name="Microsoft.Dynamics.Retail.FiscalPrinter.RussianFiscalPrinter.Properties.Settings" type="System.Configuration.ClientSettingsSection, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" requirePermission="false" /> </sectionGroup> </configSections> <AxRetailPOS OfflineDatabaseConnectionString="" StoreDatabaseConnectionString="Data Source=YOUR_MACHINE_NAME;Initial Catalog=AxRetailPOS;Integrated Security=True;Persist Security Info=False;Pooling=True;Encrypt=True;TrustServerCertificate=True" StoreId="000001" TerminalId="000001" DATAAREAID="cru" /> <system.diagnostics> <sources>  <source name="RetailNetTracer" switchValue="Warning"> <listeners> <add name="RollingXmlWriterTraceListener" /> </listeners> </source> <source name="RetailNetTracerEventLog" switchValue="Error"> <listeners> <add name="EventLogTraceListener" /> </listeners> </source> </sources>  <sharedListeners>  <add name="RollingXmlWriterTraceListener" type="Microsoft.Dynamics.Retail.Diagnostics.RollingXmlWriterTraceListener, Microsoft.Dynamics.Retail.Diagnostics" initializeData="" MaxLogFileInBytes="50000000" traceOutputOptions="ProcessId, DateTime, LogicalOperationStack" />


<wsHttpBinding> <binding name="TSWsHttpBinding" closeTimeout="00:01:00" openTimeout="00:01:00" receiveTimeout="00:10:00" sendTimeout="00:01:00" bypassProxyOnLocal="false" transactionFlow="false" hostNameComparisonMode="StrongWildcard" maxBufferPoolSize="10485760" maxReceivedMessageSize="1048576" messageEncoding="Text" textEncoding="utf-16" useDefaultWebProxy="true" allowCookies="false"> <readerQuotas maxDepth="32" maxStringContentLength="1048576" maxArrayLength="16384" maxBytesPerRead="1048576" maxNameTableCharCount="16384" /> <reliableSession ordered="true" inactivityTimeout="00:10:00" enabled="false" /> <security mode="TransportWithMessageCredential"> <transport clientCredentialType="None" proxyCredentialType="None" realm="" /> <message clientCredentialType="UserName" negotiateServiceCredential="true" algorithmSuite="Default" /> </security> </binding> <binding name="TSWsHttpBindingNoSecurity" closeTimeout="00:01:00" openTimeout="00:01:00" receiveTimeout="00:10:00" sendTimeout="00:01:00" bypassProxyOnLocal="false" transactionFlow="false" hostNameComparisonMode="StrongWildcard" maxBufferPoolSize="10485760" maxReceivedMessageSize="1048576" messageEncoding="Text" textEncoding="utf-16" useDefaultWebProxy="true" allowCookies="false"> <readerQuotas maxDepth="32" maxStringContentLength="1048576" maxArrayLength="16384" maxBytesPerRead="1048576" maxNameTableCharCount="16384" /> <reliableSession ordered="true" inactivityTimeout="00:10:00" enabled="false" /> <security mode="None"> <transport clientCredentialType="None" proxyCredentialType="None" realm="" /> <message clientCredentialType="UserName" negotiateServiceCredential="true" algorithmSuite="Default" /> </security> </binding> </wsHttpBinding> </bindings> <client> <endpoint address="net.tcp://hostname/RetailTransactionService/Service.svc/Common" binding="netTcpBinding" bindingConfiguration="TSNetTcpBinding" contract="Microsoft.Dynamics.Retail.TransactionServices.ClientProxy.ITransactionService" name="TSNetTcpEndpoint"> <identity> <dns /> </identity> </endpoint> <endpoint address="net.tcp://hostname/RetailTransactionService/Service.svc/Common"


binding="netTcpBinding" bindingConfiguration="TSNetTcpBindingNoSecurity" contract="Microsoft.Dynamics.Retail.TransactionServices.ClientProxy.ITransactionService" name="TSNetTcpEndpointNoSecurity"> <identity> <dns /> </identity> </endpoint> <endpoint address="https://hostname/RetailTransactionService/Service.svc/Common" binding="wsHttpBinding" bindingConfiguration="TSWsHttpBinding" contract="Microsoft.Dynamics.Retail.TransactionServices.ClientProxy.ITransactionService" name="TSWsHttpEndpoint"> <identity> <dns /> </identity> </endpoint> <endpoint address="http://hostname/RetailTransactionService/Service.svc/Common" binding="wsHttpBinding" bindingConfiguration="TSWsHttpBindingNoSecurity" contract="Microsoft.Dynamics.Retail.TransactionServices.ClientProxy.ITransactionService" name="TSWsHttpEndpointNoSecurity"> <identity> <dns /> </identity> </endpoint> </client> </system.serviceModel> <applicationSettings> <Microsoft.Dynamics.Retail.FiscalPrinter.Properties.Settings> <setting name="FiscalPrinterAssembly_RU" serializeAs="String"> <value>Microsoft.Dynamics.Retail.FiscalPrinter.ShtrihPrinter.dll</value> </setting> <setting name="FiscalPrinterClass_RU" serializeAs="String"> <value>Microsoft.Dynamics.Retail.FiscalPrinter.ShtrihPrinter.ShtrihPrinter</value> </setting> </Microsoft.Dynamics.Retail.FiscalPrinter.Properties.Settings> <Microsoft.Dynamics.Retail.FiscalPrinter.RussianFiscalPrinter.Properties.Settings> <setting name="TimeoutStep" serializeAs="String"> <value>100</value> </setting> <setting name="TimeoutDuration" serializeAs="String"> <value>5000</value> </setting> <setting name="SerialConnectionString" serializeAs="String"> <value>COM4:</value> </setting> <setting name="SerialConnectionBaudRate" serializeAs="String"> <value>115200</value> </setting> <setting name="SerialConnectionTimeout" serializeAs="String">

Интеграция Microsoft Dynamics AX Retail POS с ......Интеграция с...

Documents

Transcript of Интеграция Microsoft Dynamics AX Retail POS с ......Интеграция с...