Substantive.CommandExecutor

Tags: #PackageReadme #Pending/CleanUp

1. Introduction

CommandExecutor is a comprehensive library designed to facilitate the execution of various command types, including SQL scripts and PowerShell commands. With its robust architecture, the library simplifies the process of executing commands across different environments, making it an essential tool for developers looking to automate and streamline their workflows.

2. Package Readme Document

A. Installation

1. Install The Package

To integrate Substantive.CommandExecutor into project via NuGet Package Manager or by adding a package reference directly into project file (.csproj).

<PackageReference Include="Substantive.CommandExecutor" Version="1.*" />

2. Add Configuration

N/A

3. Configure Services

In program.cs, register Substantive.CommandExecutor's services with the service collection to make them available throughout application. This step is crucial for utilizing the Substantive.CommandExecutor within projects.

builder.Services.AddCommandExecutorTools();

B. Usages

The Substantive.CommandExecutor library provides two main interfaces to cater to different types of command executions: ISqlExecutor and IPowershellExecutor.

Below is a brief overview of how to use these interfaces within your applications.

SQL Command Execution

The ISqlExecutor interface allows for the asynchronous execution of SQL scripts. It is designed to work seamlessly with Entity Framework Core, enabling efficient database interactions.

public interface ISqlExecutor
{
    Task ExecuteAsync(SqlCommandOptions sqlJobOptions, CancellationToken cancellationToken = default);
}

SQL Command Options

{
  "ScriptUri": "Scripts/SqlFiles/example.sql",
  "ConnectionString": "Server=myServerAddress;Database=myDataBase;User Id=myUsername;Password=myPassword;",
  "DatabaseProvider": "MsSqlServer"
}

• ScriptUri: The relative path to the SQL script file from the application's base directory.
• ConnectionString: The database connection string required to connect to the database where the SQL commands will be executed. This should be a valid connection string for the specified database provider.
• DatabaseProvider: Specifies the database provider for which the SQL commands are intended. In this example, MsSqlServer is used, indicating Microsoft SQL Server as the target database system. Currently supported (InMemory, SQLite, MsSqlServer, and PostgreSql)

Powershell Command Execution

The IPowershellExecutor interface facilitates the asynchronous execution of PowerShell scripts to locally, providing a flexible solution for various scripting needs.

Currently the Powershell command execution only support for locally. This tools designed to be support remote execution too.

public interface IPowershellExecutor
{
    Task ExecuteAsync(PowershellCommandOptions powershellJobOptions, CancellationToken cancellationToken = default);
}

Powershell Command Options

{
  "ScriptUri": "Scripts/PowershellFiles/Script.ps1",
  "ExecutionTarget": "Local"
}

• ScriptUri: The relative path to the PowerShell script file from the application's base directory.
• ExecutionTarget: Indicates where the PowerShell script will be executed.

C. Example

To use the CommandExecutor library in your application, you would typically inject the necessary executor (ISqlExecutor or IPowershellExecutor) into your services or controllers. Then, you can call the ExecuteAsync method with the appropriate options and a cancellation token if needed.

public class ExecutionService
{
    private readonly ISqlExecutor sqlExecutor;
    private readonly IPowershellExecutor powershellExecutor;

    public ExecutionService(ISqlExecutor sqlExecutor, IPowershellExecutor powershellExecutor)
    {
        this.sqlExecutor = sqlExecutor;
        this.powershellExecutor = powershellExecutor;
    }

    public async Task ExecuteSqlScript()
    {
        var sqlOptions = new SqlCommandOptions
        {
            ScriptUri = new Uri("Scripts/SqlFiles/example.sql", UriKind.Relative),
            ConnectionString = "Server=myServerAddress;Database=myDataBase;User Id=myUsername;Password=myPassword;",
            DatabaseProvider = EFSupportedDatabaseProvider.MsSqlServer // Assuming this is an enum you have defined
        };

        await sqlExecutor.ExecuteAsync(sqlOptions);
    }

    public async Task ExecutePowershellScript()
    {
        var psOptions = new PowershellCommandOptions
        {
            ScriptUri = new Uri("Scripts/PowershellFiles/Sample.ps1", UriKind.Relative),
            ExecutionTarget = ExecutionTarget.Local
        };

        await powershellExecutor.ExecuteAsync(psOptions);
    }
}