Skip to content

Commit a6c8581

Browse files
ethanhannethanhann
committed
Update docs
1 parent 5f46613 commit a6c8581

File tree

6 files changed

+192
-56
lines changed

6 files changed

+192
-56
lines changed

‎docs/commands/index.html‎

Lines changed: 45 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -376,8 +376,8 @@
376376
</li>
377377

378378
<li class="md-nav__item">
379-
<a href="#executing-arbitrary-processes" title="Executing Arbitrary Processes" class="md-nav__link">
380-
Executing Arbitrary Processes
379+
<a href="#running-non-net-commands" title="Running non-.NET Commands" class="md-nav__link">
380+
Running non-.NET Commands
381381
</a>
382382

383383
</li>
@@ -508,8 +508,8 @@
508508
</li>
509509

510510
<li class="md-nav__item">
511-
<a href="#executing-arbitrary-processes" title="Executing Arbitrary Processes" class="md-nav__link">
512-
Executing Arbitrary Processes
511+
<a href="#running-non-net-commands" title="Running non-.NET Commands" class="md-nav__link">
512+
Running non-.NET Commands
513513
</a>
514514

515515
</li>
@@ -601,7 +601,8 @@ <h2 id="create-a-command">Create a Command<a class="headerlink" href="#create-a-
601601

602602
<h2 id="run-a-command">Run a Command<a class="headerlink" href="#run-a-command" title="Permanent link">&para;</a></h2>
603603
<p>Create a class that extends <strong>InEngine.Core.AbstractPlugin</strong> in the same assembly as the command class.
604-
Add a VerbOptions attribute, from the CommandLine namespace, that defines the name of the command. </p>
604+
Add a VerbOptions attribute, from the <strong>CommandLine</strong> namespace, that defines the name of the command. </p>
605+
<p>This class registers a command in the MyPlugin assembly called "mycommand":</p>
605606
<div class="codehilite"><pre><span></span><span class="k">using</span> <span class="nn">CommandLine</span><span class="p">;</span>
606607
<span class="k">using</span> <span class="nn">CommandLine.Text</span><span class="p">;</span>
607608
<span class="k">using</span> <span class="nn">InEngine.Core</span><span class="p">;</span>
@@ -610,7 +611,7 @@ <h2 id="run-a-command">Run a Command<a class="headerlink" href="#run-a-command"
610611
<span class="p">{</span>
611612
<span class="k">public</span> <span class="k">class</span> <span class="nc">MyPlugin</span> <span class="p">:</span> <span class="n">AbstractPlugin</span>
612613
<span class="p">{</span>
613-
<span class="na"> [VerbOption(&quot;my-command&quot;, HelpText=&quot;My example command.&quot;)]</span>
614+
<span class="na"> [VerbOption(&quot;mycommand&quot;, HelpText=&quot;My example command.&quot;)]</span>
614615
<span class="k">public</span> <span class="n">MyCommand</span> <span class="n">MyCommand</span> <span class="p">{</span> <span class="k">get</span><span class="p">;</span> <span class="k">set</span><span class="p">;</span> <span class="p">}</span>
615616
<span class="p">}</span>
616617
<span class="p">}</span>
@@ -619,9 +620,9 @@ <h2 id="run-a-command">Run a Command<a class="headerlink" href="#run-a-command"
619620

620621
<p>Download the InEngine binary distribution, from the <a href="https://github.com/InEngine-NET/InEngine.NET/releases">GitHub Releases</a> page, that matches the version of the InEngine.Core package you included.</p>
621622
<p>Copy your project's DLLs into the Plugins subdirectory included in the binary distribution.
622-
Add your plugin to the <a href="../configuration">"Plugins" list in appsettings.config</a> at the root of the binary distribution.</p>
623+
Add your plugin to the "Plugins" list in <a href="../configuration">appsettings.config</a> at the root of the binary distribution.</p>
623624
<p>Run your command:</p>
624-
<div class="codehilite"><pre><span></span>inengine.exe my-command
625+
<div class="codehilite"><pre><span></span>inengine.exe mycommand
625626
</pre></div>
626627

627628

@@ -686,11 +687,36 @@ <h3 id="progress-bar">Progress Bar<a class="headerlink" href="#progress-bar" tit
686687
</pre></div>
687688

688689

689-
<h3 id="executing-arbitrary-processes">Executing Arbitrary Processes<a class="headerlink" href="#executing-arbitrary-processes" title="Permanent link">&para;</a></h3>
690-
<p>It isn't necessary to create C# classes to utilize InEngine.NET.
691-
Arbitrary commands can be run, with an argument list by leveraging the InEngine.Core plugin's <strong>proc</strong> command.
692-
The command lists directory contents using "ls" with the "-lhp" switches:</p>
693-
<div class="codehilite"><pre><span></span>inengine.exe proc -c<span class="s2">&quot;/bin/ls&quot;</span> -a<span class="s2">&quot;-lhp&quot;</span>
690+
<h3 id="running-non-net-commands">Running non-.NET Commands<a class="headerlink" href="#running-non-net-commands" title="Permanent link">&para;</a></h3>
691+
<p>It is not necessary to create C# classes to utilize InEngine.NET.
692+
Arbitrary external programs can be run, with an optional argument list, by leveraging the InEngine.Core plugin's <strong>exec</strong> command.</p>
693+
<p>For example, create a python script called <strong>helloworld.py</strong>, make it executable, and add this to it:</p>
694+
<div class="codehilite"><pre><span></span><span class="ch">#!/usr/bin/env python</span>
695+
696+
<span class="k">print</span> <span class="s1">&#39;Hello, world!&#39;</span>
697+
</pre></div>
698+
699+
700+
<p>Whitelist the helloworld.py script in the <a href="../configuration">appsettings.json</a> file:</p>
701+
<div class="codehilite"><pre><span></span><span class="p">{</span>
702+
<span class="nt">&quot;InEngine&quot;</span><span class="p">:</span> <span class="p">{</span>
703+
<span class="err">//</span> <span class="err">...</span>
704+
<span class="nt">&quot;ExecWhitelist&quot;</span><span class="p">:</span> <span class="p">{</span>
705+
<span class="nt">&quot;helloworld&quot;</span><span class="p">:</span> <span class="s2">&quot;/path/to/helloworld.py&quot;</span>
706+
<span class="p">}</span>
707+
<span class="err">//</span> <span class="err">...</span>
708+
<span class="p">}</span>
709+
<span class="p">}</span>
710+
</pre></div>
711+
712+
713+
<p>Now execute it with the <strong>exec</strong> command:</p>
714+
<div class="codehilite"><pre><span></span>inengine <span class="nb">exec</span> --executable<span class="o">=</span><span class="s2">&quot;helloworld&quot;</span>
715+
</pre></div>
716+
717+
718+
<p>If an external executable requires arguments, use the <strong>--args</strong> argument:</p>
719+
<div class="codehilite"><pre><span></span>inengine <span class="nb">exec</span> --executable<span class="o">=</span><span class="s2">&quot;foo&quot;</span> --args<span class="o">=</span><span class="s2">&quot;--version&quot;</span>
694720
</pre></div>
695721

696722

@@ -706,7 +732,8 @@ <h2 id="view-commands">View Commands<a class="headerlink" href="#view-commands"
706732
<p>The <strong>InEngine.Core</strong> library is itself a plugin that contains queueing, scheduling, and other commands. </p>
707733
</div>
708734
<h2 id="view-a-commands-help-text">View a Command's Help Text<a class="headerlink" href="#view-a-commands-help-text" title="Permanent link">&para;</a></h2>
709-
<p>Run the command with the -h or --help arguments.</p>
735+
<p>Run the command with the -h or --help arguments to see help text.</p>
736+
<p>This command prints the publish command's help text, from the core plugin:</p>
710737
<div class="codehilite"><pre><span></span>inengine.exe queue:publish -h
711738
</pre></div>
712739

@@ -715,14 +742,14 @@ <h2 id="view-a-commands-help-text">View a Command's Help Text<a class="headerlin
715742
<div class="codehilite"><pre><span></span>InEngine 3.x
716743
Copyright © 2017 Ethan Hann
717744

718-
--command-plugin Required. The name of a command plugin file, e.g.
745+
--plugin Required. The name of a command plugin file, e.g.
719746
InEngine.Core
720747

721-
--command-verb A plugin command verb, e.g. echo
748+
--command A command name, e.g. echo
722749

723-
--command-class A command class name, e.g.
750+
--class A command class, e.g.
724751
InEngine.Core.Commands.AlwaysSucceed. Takes precedence
725-
over --command-verb if both are specified.
752+
over --command if both are specified.
726753

727754
--args An optional list of arguments to publish with the
728755
command.

‎docs/configuration/index.html‎

Lines changed: 59 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -387,6 +387,13 @@
387387
Top-level Settings
388388
</a>
389389

390+
</li>
391+
392+
<li class="md-nav__item">
393+
<a href="#mail-settings" title="Mail Settings" class="md-nav__link">
394+
Mail Settings
395+
</a>
396+
390397
</li>
391398

392399
<li class="md-nav__item">
@@ -435,6 +442,13 @@
435442
Top-level Settings
436443
</a>
437444

445+
</li>
446+
447+
<li class="md-nav__item">
448+
<a href="#mail-settings" title="Mail Settings" class="md-nav__link">
449+
Mail Settings
450+
</a>
451+
438452
</li>
439453

440454
<li class="md-nav__item">
@@ -464,9 +478,17 @@ <h1 id="configuration">Configuration<a class="headerlink" href="#configuration"
464478
The <strong>-c, --configuration</strong> argument can also be used to specify an alternate configuration file.</p>
465479
<div class="codehilite"><pre><span></span><span class="p">{</span>
466480
<span class="nt">&quot;InEngine&quot;</span><span class="p">:</span> <span class="p">{</span>
467-
<span class="nt">&quot;Plugins&quot;</span><span class="p">:</span> <span class="p">[</span>
468-
<span class="s2">&quot;path/to/MyCommandPlugin&quot;</span>
469-
<span class="p">],</span>
481+
<span class="nt">&quot;Plugins&quot;</span><span class="p">:</span> <span class="p">{</span>
482+
<span class="nt">&quot;MyPlugin&quot;</span><span class="p">:</span> <span class="s2">&quot;/path/to/plugin/assembly&quot;</span>
483+
<span class="p">},</span>
484+
<span class="nt">&quot;ExecWhitelist&quot;</span><span class="p">:</span> <span class="p">{</span>
485+
<span class="nt">&quot;foo&quot;</span><span class="p">:</span> <span class="s2">&quot;/path/to/foo.exe&quot;</span>
486+
<span class="p">},</span>
487+
<span class="nt">&quot;Mail&quot;</span><span class="p">:</span> <span class="p">{</span>
488+
<span class="nt">&quot;Host&quot;</span><span class="p">:</span> <span class="s2">&quot;localhost&quot;</span><span class="p">,</span>
489+
<span class="nt">&quot;Port&quot;</span><span class="p">:</span> <span class="mi">25</span><span class="p">,</span>
490+
<span class="nt">&quot;From&quot;</span><span class="p">:</span> <span class="s2">&quot;no-reply@inengine.net&quot;</span>
491+
<span class="p">},</span>
470492
<span class="nt">&quot;Queue&quot;</span><span class="p">:</span> <span class="p">{</span>
471493
<span class="nt">&quot;UseCompression&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
472494
<span class="nt">&quot;PrimaryQueueConsumers&quot;</span><span class="p">:</span> <span class="mi">16</span><span class="p">,</span>
@@ -495,8 +517,40 @@ <h2 id="top-level-settings">Top-level Settings<a class="headerlink" href="#top-l
495517
<tbody>
496518
<tr>
497519
<td>Plugins</td>
498-
<td>array of strings</td>
499-
<td>A list of paths of plugin assemblies, with ".dll" omitted from the assembly name.</td>
520+
<td>object</td>
521+
<td>A set of key/value pairs, where the value is the directory where the plugin is located and the key is the plugin name sans .dll extension.</td>
522+
</tr>
523+
<tr>
524+
<td>ExecWhitelist</td>
525+
<td>object</td>
526+
<td>A set of key/value pairs, where the value is the file system path of an executable and the key is a command alias.</td>
527+
</tr>
528+
</tbody>
529+
</table>
530+
<h2 id="mail-settings">Mail Settings<a class="headerlink" href="#mail-settings" title="Permanent link">&para;</a></h2>
531+
<table>
532+
<thead>
533+
<tr>
534+
<th>Setting</th>
535+
<th>Type</th>
536+
<th>Description</th>
537+
</tr>
538+
</thead>
539+
<tbody>
540+
<tr>
541+
<td>Host</td>
542+
<td>string</td>
543+
<td>The hostname of an SMTP server.</td>
544+
</tr>
545+
<tr>
546+
<td>Port</td>
547+
<td>integer</td>
548+
<td>The port of an SMTP server.</td>
549+
</tr>
550+
<tr>
551+
<td>From</td>
552+
<td>string</td>
553+
<td>The default email address used to send email from.</td>
500554
</tr>
501555
</tbody>
502556
</table>

‎docs/index.html‎

Lines changed: 30 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -474,7 +474,7 @@ <h2 id="how-does-it-work">How does it work?<a class="headerlink" href="#how-does
474474
<p>InEngine.NET uses a plugin system to dynamically load .NET assemblies and execute code.
475475
It also has a built-in command for launching external non-.NET programs.</p>
476476
<p>Get started by pulling the binaries from the <a href="https://github.com/InEngine-NET/InEngine.NET/releases">latest release</a> on GitHub.</p>
477-
<p>Then run a command the <strong>echo</strong> command from the core plugin:</p>
477+
<p>Then run the <strong>echo</strong> command from the core plugin:</p>
478478
<div class="codehilite"><pre><span></span>inengine.exe <span class="nb">echo</span> --text<span class="s2">&quot;Hello, world&quot;</span>
479479
</pre></div>
480480

@@ -495,28 +495,49 @@ <h2 id="how-does-it-work">How does it work?<a class="headerlink" href="#how-does
495495

496496

497497
<h2 id="how-does-queueing-work">How does queueing work?<a class="headerlink" href="#how-does-queueing-work" title="Permanent link">&para;</a></h2>
498-
<p>There are a lot of <a href="./queuing">queuing</a> features, but this is the gist...</p>
499498
<p>Want to queue our example echo command to run in the background or possibly on another server?</p>
500499
<p>Use the core plugin's <strong>queue:publish</strong> command:</p>
501-
<div class="codehilite"><pre><span></span>inengine.exe queue:publish --command-plugin<span class="o">=</span>InEngine.Core --command-verb<span class="o">=</span><span class="nb">echo</span> --args <span class="s2">&quot;text=Hello, world&quot;</span>
500+
<div class="codehilite"><pre><span></span>inengine.exe queue:publish --plugin<span class="o">=</span>InEngine.Core --command<span class="o">=</span><span class="nb">echo</span> --args <span class="s2">&quot;text=Hello, world&quot;</span>
502501
</pre></div>
503502

504503

505504
<p>How do we consume that queued echo command?</p>
506-
<p>Use the core plugin's <strong>queue:consume</strong> command of course:</p>
505+
<p>Use the core plugin's <strong>queue:consume</strong> command:</p>
507506
<div class="codehilite"><pre><span></span>inengine.exe queue:consume
508507
</pre></div>
509508

510509

511510
<h2 id="how-do-i-run-non-net-commands">How do I run non-.NET commands?<a class="headerlink" href="#how-do-i-run-non-net-commands" title="Permanent link">&para;</a></h2>
512-
<p>There is a special <strong>proc</strong> command in the core plugin that allows for the execution of any program you can run at the command line. </p>
513-
<p>For example, create a python script called <strong>helloworld.py</strong> that contains this:</p>
514-
<div class="codehilite"><pre><span></span><span class="k">print</span> <span class="s1">&#39;Hello, world!&#39;</span>
511+
<p>There is a special <strong>exec</strong> command in the core plugin that allows for the execution of any program you can run at the command line. </p>
512+
<p>For example, create a python script called <strong>helloworld.py</strong>, make it executable, and add this to it:</p>
513+
<div class="codehilite"><pre><span></span><span class="ch">#!/usr/bin/env python</span>
514+
515+
<span class="k">print</span> <span class="s1">&#39;Hello, world!&#39;</span>
516+
</pre></div>
517+
518+
519+
<p>Whitelist the "helloworld" executable in the <a href="./configuration">appsettings.json</a> file:</p>
520+
<div class="codehilite"><pre><span></span><span class="p">{</span>
521+
<span class="nt">&quot;InEngine&quot;</span><span class="p">:</span> <span class="p">{</span>
522+
<span class="err">//</span> <span class="err">...</span>
523+
<span class="nt">&quot;ExecWhitelist&quot;</span><span class="p">:</span> <span class="p">{</span>
524+
<span class="nt">&quot;helloworld&quot;</span><span class="p">:</span> <span class="s2">&quot;/path/to/helloworld.py&quot;</span>
525+
<span class="p">}</span>
526+
<span class="err">//</span> <span class="err">...</span>
527+
<span class="p">}</span>
528+
<span class="p">}</span>
529+
</pre></div>
530+
531+
532+
<p>Now execute it with the <strong>exec</strong> command:</p>
533+
<div class="codehilite"><pre><span></span>inengine <span class="nb">exec</span> --executable<span class="o">=</span><span class="s2">&quot;helloworld&quot;</span>
515534
</pre></div>
516535

517536

518-
<p>Now execute it with the <strong>proc</strong> command:</p>
519-
<div class="codehilite"><pre><span></span>inengine proc --command<span class="o">=</span>/usr/bin/python --args<span class="o">=</span>helloworld.py
537+
<p>Why would you want to do this?
538+
It opens up the possibility of running shell scripts, ETLs, Java programs, etc. in the background or on a schedule. </p>
539+
<p>The example python script can be queued:</p>
540+
<div class="codehilite"><pre><span></span>inengine queue:publish --plugin<span class="o">=</span>InEngine.Core --command<span class="o">=</span><span class="nb">exec</span> --args<span class="o">=</span><span class="s2">&quot;executable=helloworld&quot;</span>
520541
</pre></div>
521542

522543

‎docs/queuing/index.html‎

Lines changed: 27 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -424,6 +424,13 @@
424424
With Lambda Expressions
425425
</a>
426426

427+
</li>
428+
429+
<li class="md-nav__item">
430+
<a href="#with-the-exec-command" title="With the "exec" Command" class="md-nav__link">
431+
With the "exec" Command
432+
</a>
433+
427434
</li>
428435

429436
<li class="md-nav__item">
@@ -634,6 +641,13 @@
634641
With Lambda Expressions
635642
</a>
636643

644+
</li>
645+
646+
<li class="md-nav__item">
647+
<a href="#with-the-exec-command" title="With the "exec" Command" class="md-nav__link">
648+
With the "exec" Command
649+
</a>
650+
637651
</li>
638652

639653
<li class="md-nav__item">
@@ -833,6 +847,16 @@ <h3 id="with-lambda-expressions">With Lambda Expressions<a class="headerlink" hr
833847
</pre></div>
834848

835849

850+
<h3 id="with-the-exec-command">With the "exec" Command<a class="headerlink" href="#with-the-exec-command" title="Permanent link">&para;</a></h3>
851+
<p>The <strong>exec</strong> command allows for external programs to be executed.</p>
852+
<div class="codehilite"><pre><span></span>inengine queue:publish --plugin<span class="o">=</span>InEngine.Core --command<span class="o">=</span>exe --args<span class="o">=</span><span class="s2">&quot;command=/usr/bin/python&quot;</span> <span class="s2">&quot;args=--version&quot;</span>
853+
</pre></div>
854+
855+
856+
<div class="admonition note">
857+
<p class="admonition-title">Do not include "--" for the command and args parameters.</p>
858+
<p>This is purely to make parsing easier internally.</p>
859+
</div>
836860
<h3 id="sequentially-in-a-chain">Sequentially In a Chain<a class="headerlink" href="#sequentially-in-a-chain" title="Permanent link">&para;</a></h3>
837861
<p>Chained commands run in the order specified.
838862
This is useful for when order matters.</p>
@@ -885,17 +909,17 @@ <h3 id="from-the-command-line">From the Command Line<a class="headerlink" href="
885909
<p>Commands can be published from the command line as well.
886910
Note that all queue commands reside in the <strong>InEngine.Core</strong> plugin.
887911
This is an example of how to publish a command from the CLI by specifying the command's plugin, class name, and arguments:</p>
888-
<div class="codehilite"><pre><span></span>inengine.exe queue:publish --command-plugin<span class="o">=</span>MyCommandPlugin --command-class<span class="o">=</span>MyCommand --args <span class="s2">&quot;text=bar&quot;</span>
912+
<div class="codehilite"><pre><span></span>inengine.exe queue:publish --plugin<span class="o">=</span>MyCommandPlugin --class<span class="o">=</span>MyCommand --args <span class="s2">&quot;text=bar&quot;</span>
889913
</pre></div>
890914

891915

892916
<p>There is an "Echo" command in the <em>InEngine.Core</em> package. It is useful for end-to-end testing with the queue feature.</p>
893-
<div class="codehilite"><pre><span></span>inengine.exe queue:publish --command-plugin<span class="o">=</span>InEngine.Core --command-class<span class="o">=</span>InEngine.Core.Commands.Echo --args <span class="s2">&quot;text=foo&quot;</span>
917+
<div class="codehilite"><pre><span></span>inengine.exe queue:publish --plugin<span class="o">=</span>InEngine.Core --class<span class="o">=</span>InEngine.Core.Commands.Echo --args <span class="s2">&quot;text=foo&quot;</span>
894918
</pre></div>
895919

896920

897921
<p>The command verb can also be specified instead of the full class name:</p>
898-
<div class="codehilite"><pre><span></span>inengine.exe queue:publish --command-plugin<span class="o">=</span>InEngine.Core --command-verb<span class="o">=</span>echo--args <span class="s2">&quot;text=foo&quot;</span>
922+
<div class="codehilite"><pre><span></span>inengine.exe queue:publish --plugin<span class="o">=</span>InEngine.Core --command<span class="o">=</span>echo--args <span class="s2">&quot;text=foo&quot;</span>
899923
</pre></div>
900924

901925

0 commit comments

Comments
 (0)