What are instructions?

Instructions are commands for PCB-Investigator that are queued and executed sequentially. This means they will be executed in the order that they were sent in.
Instructions can be used to automate tasks, such as loading a file, running a script, or exporting data. They are especially useful for automating long-running tasks, because you can queue them and check the status later.

How do I add an instruction?

Adding new available instructions

To add an instruction using the PCBI_RemoteControlServer.PCBI_Connection.AddInstruction method, follow these steps:

1. Understand the Method Signature:

   public void AddInstruction(string name, Func<Entities.RequestDto, Task<Entities.InstructionResult>> handler, string description = "")

   • name: A string representing the name of the instruction.
   • handler: A Func delegate that takes an Entities.RequestDto and returns a Task<Entities.InstructionResult>. This is the function that will be executed when the instruction is called.
   • description: An optional string providing a description of the instruction.
2. Create the Handler Function:

   The handler function should match the signature Func<Entities.RequestDto, Task<Entities.InstructionResult>>. Here is an example of how to create such a function:

   public async Task<Entities.InstructionResult> MyInstructionHandler(Entities.RequestDto request)
   {
       // Your logic here
       var result = new Entities.InstructionResult();
       // Populate result based on the request
       return await Task.FromResult(result);
   }

3. Add the Instruction:

   Use the AddInstruction method to register your new instruction. Here is an example:

   
                       PCBI_RemoteControlServer.PCBI_Connection connection; // This is a placeholder. Get the currenly loaded Plugin instance.
                       connection.AddInstruction("MyInstruction", MyInstructionHandler, "This is a sample instruction.");

4. Example Usage:

   Here is a complete example that demonstrates how to add an instruction:

   
   using System;
   using System.Threading.Tasks;
   using PCBI_RemoteControlServer;
   
   public async Task<Entities.InstructionResult> MyInstructionHandler(Entities.RequestDto request)
   {
       var result = new Entities.InstructionResult();
       // Implement your logic here
       return await Task.FromResult(result);
   }
   
   public void RegisterInstruction()
   {
       PCBI_RemoteControlServer.PCBI_Connection connection; // This is a placeholder. Get the currenly loaded Plugin instance.
       connection.AddInstruction("MyInstruction", MyInstructionHandler, "This is a sample instruction.");
   }
                   

Adding an instruction to the queue

Once an instruction is made available, it can be queued with the HTTP request POST /instructions described on the homepage.