6.2. ICommandBuilder 移行ガイド（StarPRNT V5搭載機能）
本ページは、プリンターモデル依存を最小限に抑えることを目的とした ICommandBuilder 移行ガイドです。
ICommandBuilder とは、従来のバイナリ形式でのコマンド生成ではなくヒューマンリーダブルなコマンド生成を可能にする機能で、StarPRNT V5.0以降の拡張ライブラリ（以降、 StarIOExtension ）に搭載しています。
今までは開発者がプリンターエミュレーションの仕様を理解した上でコマンドを生成しなければいけませんでしたが、本機能により学習コストを抑えることができ、機種追加時の工数削減も期待できます。
本ページを参考に ICommandBuilder をご活用ください。
6.2.1. 必要な作業内容一覧
ICommandBuilder への移行とプリンターモデルの追加に必要な作業は以下です。
重要
プリンターモデルの組み合わせによっては、 portSettings指定の変更 も必要になります。
6.2.2. StarIOExtension の導入
プロジェクトに StarIOExtension が組み込まれていることを確認してください。 各ライブラリは同一SDKバージョンの物をご利用ください。
Nugetパッケージ
dllファイルを使用する場合の一覧
StarIO.dll
StarIOExtension.dll
SMCloudServicesSolution.dll
ライブラリ導入手順の詳細は、 ライブラリ追加方法 に記載しています。
6.2.3. APIとコマンド作成方法の変更方法（ICommandBuilderの導入）
全体フローの違い
下記フローに示すように、 ICommandBuilder の導入にコマンド生成部以外の変更は必要ありません。
印刷データ作成（プリンター内蔵フォント）プログラム上の変更
レシート上の文字に使用されるプリンター内蔵フォント印刷は、以下サンプルのように変わります。実際には利用している機能に合わせて変更をお願いします。
対応している機能の一覧は ICommandBuilder をご確認ください。
注釈
TSP100シリーズはプリンターフォントに対応していません。 印刷データ作成（画像データ）プログラム上の変更 をご確認ください。
string command = "\x1b\x40"; // Initialization
command += "\x1b\x1d\x61\x01"; // Alignment
command += "Hello world";
command += "\x1b\x64\x02"; // Cut paper
ICommandBuilder builder = StarIoExt.CreateCommandBuilder(emulation);
builder.BeginDocument();
builder.AppendAlignment(AlignmentPosition.Right);
builder.Append(Encoding.GetEncoding(encoding).GetBytes("Hello world").AsBuffer());
builder.AppendCutPaper(CutPaperAction.PartialCutWithFeed);
builder.EndDocument();
builder.commands
印刷データ作成（画像データ）プログラム上の変更
レシート上の店舗ロゴなどに使用される画像データ印刷は、以下サンプルのように変わります。実際には利用している機能に合わせて変更をお願いします。
対応している機能の一覧は ICommandBuilder をご確認ください。
using (var stream = Properties.Resources.star_logo_image)
{
starLogoImage = new Bitmap(stream);
}
ICommandBuilder builder = StarIoExt.CreateCommandBuilder(emulation);
builder.BeginDocument();
await builder.AppendBitmap(starLogoImage, true);
builder.AppendCutPaper(CutPaperAction.PartialCutWithFeed);
builder.EndDocument();
builder.commands
6.2.4. プリンターモデルの追加方法
プリンターモデルの追加や移行をする場合でも、プリンターコマンドの生成に ICommandBuilder を利用しているのであれば、ほとんどのケースはエミュレーション指定の変更だけで完了します。
ただし、一部状況においては追加の変更が必要になるため、下記案内を参考に変更をお願いします。
Emulationの指定方法（ ICommandBuilder ）
mC-Print3とそれ以外のプリンターでは、搭載しているエミュレーションが異なることがあります。
Emulation のページで対応エミュレーションを確認し、 ICommandBuilder インスタンス生成時にエミュレーション指定を変更してください。
例として、TSP100/TSP650IIとmC-Print3では、下記表に沿ったエミュレーション指定の変更が必要です。
Printer |
Emulation |
|---|---|
TSP650II |
StarLine |
TSP100 |
StarGraphic |
mC-Print3 |
StarPRNT |
// TSP650II (StarLine)
// Emulation emulation = Emulation.StarLine;
// TSP100 (StarGraphic)
// Emulation emulation = Emulation.StarGraphic;
// mC-Print3 (StarPRNT)
Emulation emulation = Emulation.StarPRNT;
ICommandBuilder builder = StarIoExt.CreateCommandBuilder(emulation);
SearchPrinter の検索方法
SearchPrinter によるプリンターの検索方法は同一です。
検索で得られるモデル名をアプリケーション内で何かしらの判別に利用している場合は、対応が必要になります。
例として、検索結果に含まれるプリンターモデル名は下記の通りです。
LANインターフェース
Printer
Model Name (PortInfo)
mC-Print2
"MCP21", "MCP20"
mC-Print3
"MCP31", "MCP30"
mC-Label3
"MCL32"
TSP100IV
"TSP143IV"
TSP100IV SK
"TSP143IV"
TSP100IIILAN
"TSP143IIILAN", "TSP143IIIW"
TSP650II
"TSP654"
TSP700II
"TSP743II"
TSP800II
"TSP847II"
SP700
"SP712", "SP742", "SP717", "SP747"
USBインターフェース
Printer
Model Name (PortInfo)
mC-Print2
"Star MCP21/20"
mC-Print3
"Star MCP31", "Star MCP30"
mC-Label3
"Star MCL32"
mPOP
"Star POP10"
TSP100IV
"Star TSP100"
TSP100IV SK
"Star TSP100"
TSP100III
"Star TSP100 Cutter (TSP143)"
TSP100IIU+
"Star TSP100 Cutter (TSP143)"
TSP650II
"TSP650II Cutter (TSP654II)"
Bluetoothインターフェース
Printer
Model Name (PortInfo)
mC-Print2
"mC-Print2-XXXXX"
mC-Print3
"mC-Print3-XXXXX"
mC-Label3
"mC-Label3-XXXXX"
mPOP
"STAR mPOP-XXXXX"[1], "mPOP-XXXXX"[2] TSP100III
"TSP100-XXXXX"
TSP650II
"Star Micronics"
TSP700II
"Star Micronics"
TSP800II
"Star Micronics"
SP700
"Star Micronics"
SM-S210i
"Star Micronics"[3], "SM-S210I-XXXXX"[4] SM-S230i
"Star Micronics"[3], "SM-S230I-XXXXX"[4] SM-T300
"Star Micronics"[3], "SM-T300-XXXXX"[4] SM-T300i
"Star Micronics"[3], "SM-T300i-XXXXX"[4] SM-T400i
"Star Micronics"[3], "SM-T400i-XXXXX"[4] SM-L200
"Star Micronics"
SM-L300
"Star Micronics"
XXXXX : 製品ごと異なる5桁の識別番号
| [1] | POP10の場合 |
| [2] | POP10CBIの場合 |
| [3] | ファームウェアバージョン5.0未満 |
| [4] | ファームウェアバージョン5.0以降 |
GetPort - portName引数の指定方法
portName の指定に SearchPrinter の戻り値（ PortInfo ）を利用している場合、引数の変更は必要ありません。
ただし、引数を直接設定（固定値など）している場合は、デバイス名の初期値がmC-Print3とそれ以外で異なるため、引数を変更しなければいけない可能性があります。
例として、TSP100/TSP650IIとmC-Print3の初期値は下記の通りです。
Bluetoothインターフェース
Printer |
Bluetooth DeviceName |
|---|---|
TSP100 |
"TSP100-XXXXX" |
TSP650II |
"Star Micronics" |
mC-Print3 |
"mC-Print3-XXXXX" |
XXXXX : 製品ごと異なる5桁の識別番号
USB Printer Classインターフェース
Printer |
USB Printerキュー名 |
|---|---|
TSP100III |
"Star TSP100 Cutter (TSP143)" |
TSP650II |
"TSP650II Cutter (TSP654II)" |
mC-Print3 |
"Star MCP31" , "Star MCP30" |
IPort port = null;
string portSettings = "";
// TSP650II (Bluetooth)
// string portName = "BT:Star Micronics";
// TSP100 (Bluetooth)
// string portName = "BT:TSP100-XXXXX";
// mC-Print3 (Bluetooth)
// string portName = "BT:mC-Print3-XXXXX";
// mC-Print3 (USB Printer Class)
// string portName = "Star MCP31";
// string portName = "Star MCP30";
// No changes required if used "BT:"
string portName = "BT:";
port = Factory.I.GetPort(portName, portSettings, timeout)
その他インターフェース
プリンター固有のデバイス名はありません。 GetPort のページを参考に、インターフェースごと適切な portName を設定してください。
GetPort - portSettings引数の指定方法
各プリンターモデルで適用すべき識別子が異なることがあります。 GetPort のページ「2. portSettings 引数」を参考に変更してください。
例として、TSP100/TSP650IIとmC-Print3の portSettings は同一です。
Printer |
portSettings |
|---|---|
TSP100 |
"" |
TSP650II |
"" |
mC-Print3 |
"" |
IPort port = null;
string portName = "BT:";
// string portSettings = "l10000"
string portSettings = "";
port = Factory.I.GetPort(portName, portSettings, timeout)
印字領域の指定方法
プリンターモデルの組み合わせによっては印字領域設定の初期値が異なります。必要に応じて AppendPrintableArea で領域を指定してください。
AppendBitmap などを用いてグラフィックデータを印刷している場合は、移行先プリンターモデルの印字領域に合わせてレイアウト変更をお願いします。
6.2.5. コマンド生成からデータ送信までのコード上の流れ
コマンド生成から書き込みまでの一連です。実際には下記関数を非UIスレッドで実行してください。
public static void PrintSample(byte[] commands, string portName, string portSettings, int timeout)
{
CommunicationResult result = CommunicationResult.ErrorUnknown;
IPort port = null;
try
{
Emulation emulation = Emulation.StarPRNT;
ICommandBuilder builder = StarIoExt.CreateCommandBuilder(emulation);
builder.BeginDocument();
builder.AppendAlignment(AlignmentPosition.Right);
builder.Append(Encoding.GetEncoding(encoding).GetBytes("Hello world").AsBuffer());
builder.AppendCutPaper(CutPaperAction.PartialCutWithFeed);
builder.EndDocument();
String portName = "BT:";
String portSettings = "";
result = CommunicationResult.ErrorOpenPort;
port = Factory.I.GetPort(portName, portSettings, timeout);
StarPrinterStatus status;
result = CommunicationResult.ErrorBeginCheckedBlock;
status = port.BeginCheckedBlock();
if (status.Offline)
{
throw new PortException("Printer is Offline.");
}
result = CommunicationResult.ErrorWritePort;
uint commandsLength = (uint)commands.Length;
uint writtenLength = port.WritePort(commands, 0, commandsLength);
if (writtenLength != commandsLength)
{
throw new PortException("WritePort failed.");
}
result = CommunicationResult.ErrorEndCheckedBlock;
status = port.EndCheckedBlock();
if (status.Offline == true)
{
throw new PortException("Printer is Offline.");
}
result = CommunicationResult.Success;
}
catch (PortException) {} finally
{
if (port != null)
{
Factory.I.ReleasePort(port);
}
}
return result;
}