CliOptions

The pi-cli framework uses the options pattern to provide strongly typed access to groups of related settings. When configuration settings are isolated by scenario into separate classes, the host CLI terminal adheres to two crucial software engineering principles:

  • Interface Segregation Principle (ISP) or Encapsulation: Scenarios (classes) that depend on configuration settings depend only on the configuration settings that they use.
  • Separation of Concerns: Settings for different parts of the app aren't dependent or coupled to one another. Options also provide a mechanism to validate configuration data. For more information, see the Options validation section.

This article provides information on all the supported configuration options by the pi-cli framework.

CheckerOptions

The command and argument checker options.

Note: The checker options are not filters. The command execution is blocked if any check fails.

AllowObsoleteArgument

Determines whether the checker allows a command to run with an obsolete argument.

The obsolete argument value check is done at runtime only if a user or an application attempts to run the command and passes an obsolete argument value. This option has no effect if the command supports an obsolete argument, but the user did not give its value through the command string.

StrictArgumentValueType

Determines whether the checker checks an argument value type. If this option is enabled, the checker will try to map an argument value to its corresponding .NET value type. If the mapping fails, the command will not run.

Example:

    pi lic gen --lic-edition community --expiry 365 --nbf "26-Apr-2022 14:36:11" --test

In the code example above, let's assume the command pi lic gen defines 4 arguments:

  • lic-edition (string)
  • expiry (int)
  • nbf (date and time)
  • test (boolean)

If the strict argument value type check is enabled, the checker will do an automatic type check and ensure that argument lic-edition is a string, expiry is an int, nbf is a valid date and time, and test is a bool. If any check fails, the command will not run.

Note: If this option is not enabled, the checker will allow all the argument values as strings.

ExtractorOptions

The command and argument extraction options.

ArgumentAlias

Determines whether the extractor support extracting an argument by alias.

Example:

    options.Extractor.ArgumentAlias = true;
    dotnet build --configuration Release 
    dotnet build -c Release

Argument alias supports the apps that identify a command argument with an id and an alias string. For modern console apps, we recommend using just an argument identifier. We have optimized the core data model to work with argument id. An app should not identify the same argument with multiple strings. Using an alias will degrade the performance.

ArgumentAliasPrefix

The argument alias prefix if ArgumentAlias is enabled. Defaults to -.

Example:

    dotnet build -c Release 

    options.Extractor.ArgumentAliasPrefix = ":";
    dotnet build :c Release

Note: The argument alias prefix must be a single Unicode character, and it cannot be null or whitespace.

ArgumentPrefix

The argument prefix. Defaults to -.

Example:

    dotnet build -configuration Release 

    options.Extractor.ArgumentPrefix = "--";
    dotnet build --configuration Release

Note: The argument prefix must be a single Unicode character, and it cannot be null or whitespace.

ArgumentValueSeparator

The argument value separator. Defaults to =.

Example:

    dotnet build -configuration=Release 

    options.Extractor.ArgumentValueSeparator = " ";
    dotnet build -configuration Release     

    options.Extractor.ArgumentValueSeparator = ":";
    dotnet build -configuration:Release     

    options.Extractor.ArgumentValueSeparator = ">";
    dotnet build -configuration>Release

Note: The argument value separator must be a single Unicode character, and it can be a single whitespace character.

ArgumentValueWithIn

An optional token within which to extract an argument value. Default to null.

Example:

    pi print -message=This is a string without quotes

    options.Extractor.ArgumentValueWithIn = "\"";
    pi print -message="This is a string within quotes"

    options.Extractor.ArgumentValueWithIn = "~";
    pi print -message=~This is a string within tilda~

Note: The optional argument within token must be a single Unicode character. If set it cannot be null or whitespace.

CommandIdRegex

The Regex pattern for command identifier. Defaults to ^[A-Za-z0-9_-]*$.

DefaultArgument

Determines whether command supports default argument.

Example:

    dotnet restore -p ./projects/app1/app1.csproj

    options.Extractor.DefaultArgument = true;
    dotnet restore ./projects/app1/app1.csproj

In the code example above, let's assume the command dotnet restore has a default argument p. The command string's argument value ./projects/app1/app1.csproj is automatically set to the default argument p.

DefaultArgumentValue

Determines whether argument support default value.

Example:

    dotnet build ./projects/app1/app1.csproj -c RELEASE

    options.Extractor.DefaultArgumentValue = true;
    dotnet build ./projects/app1/app1.csproj

In the code example above, let's assume the command dotnet build has defined a required configuration argument c with a default value DEBUG. Even though the command string did not specify any configuration value, the extractor will automatically set the c value to DEBUG during the command run.

Separator

The command string separator. Defaults to a single whitespace .

Example:

    pi gen guid --short
    dotnet publish --framework netcoreapp3.1 --runtime osx.10.11-x64
    डॉटनेट पब्लिश --कॉन्फिग रिलीज --सैंपल हिंदी

    options.Extractor.Separator = ":";
    options.Extractor.ArgumentValueSeparator = " ";
    dotnet:publish:--framework netcoreapp3.1:--runtime osx.10.11-x64
    pi:gen:guid:--short

Note: The command string separator must be a single Unicode character, and it can be a whitespace character.

HandlerOptions

The handler options.

DataTypeHandler

The data type handler. Its value can be null, default or custom. The default and custom are reserved for future releases.

  • null indicates no data type handler.
  • 💁 default to be defined.
  • 💁 custom to be defined.

By default the value is set to null.

ErrorHandler

The hosting and routing error handler. Its value can be default or custom. The command router receives an error or exception during the command routing, extraction, checker, or execution. On error, it forwards it to the @PerpetualIntelligence.Cli.Commands.Handlers.IErrorHandler or @PerpetualIntelligence.Cli.Commands.Handlers.IExceptionHandler.

  • default handler prints the error information in the CLI terminal.
  • custom handler allows application authors to define a custom error handler to process and publish the error according to their needs. E.g., app authors can publish the errors to a central log or on their cloud backend for audit purposes.

By default the value is set to default.

LicenseHandler

The license handler. Its value can be online, offline, or byol. The offline or byol are reserved for future releases.

  • online handler checks your license key online. Your CLI terminal needs network access during startup.
  • 🔜 offline handler checks your license key offline. Your CLI terminal does not need network access during startup.
  • 🔜 boyl handler allows you to bring you own license certificate to check the license key. Your CLI terminal may need network access during startup.

By default the value is set to online.

ServiceHandler

The hosting and routing dependency injection services. Its value can be default or custom. The custom is reserved for future releases.

  • default handler provides default DI service implementations for command router, extractor, checker and runner.
  • 🔜 custom handler allows application authors to define a custom DI services implementations.

By default the value is set to default.

StoreHandler

The command and argument store handler. Its value can be in-memory, json or custom. The json or custom are reserved for future releases.

  • in-memory handler provides in memory command and argument descriptions.
  • 🔜 json handler provides command and argument descriptions in a JSON file.
  • 🔜 custom handler allows application authors to provide command and argument descriptions from a custom store such as Entity framework or cloud databases REST API.

By default the value is set to in-memory.

TextHandler

The hosting and routing command string text handler. Its value can be unicode or ascii. The ascii is reserved for future releases.

  • unicode handler supports Unicode command strings.
  • 🔜 ascii handler supports ASCII command strings.

By default the value is set to unicode. Currently we only support left-to-right languages.

HttpOptions

The HTTP configuration options.

HttpClientName

The logical name to create and configure HttpClient instance. The framework uses IHttpClientFactory and the configured name to create an instance of HttpClient.

LicensingOptions

The licensing configuration options. Please visit licensing to generate license keys and access your identifiers.

AuthorizedApplicationId

The authorized application id. This is also the auth_apps claim from your license key.

ConsumerTenantId

The consumer tenant id.

KeySource

The license key source. Defaults to @PerpetualIntelligence.Protocols.Licensing.SaaSKeySources.JsonFile.

LicenseKey

The license key or the file path containing license key.

ProviderId

The license SaaS provider id or the provider tenant id. Defaults to @PerpetualIntelligence.Protocols.Licensing.SaaSProviders.PerpetualIntelligence.

Subject

The subject or a licensing context to check the license. Your subscription id or any other domain identifier usually establishes your licensing context.

LoggingOptions

The logging configuration options.

ObscureErrorArgumentString

The string used to obscure error description arguments. The default value is ****.

Example:

    // Obscure error args
    options.Logging.ObsureErrorArguments = true;
    options.Logging.ObscureErrorArgumentString = "####";
    [10:49:10 error] The license is not extracted or license is not valid. Please ensure you use the CLI hosted service. service=####

    options.Logging.ObsureErrorArguments = false;
    options.Logging.ObscureErrorArgumentString = "####";
    [10:49:10 error] The license is not extracted or license is not valid. Please ensure you use the CLI hosted service. service=PerpetualIntelligence.Cli.Integration.CliHostedService

ObsureErrorArguments

Obscures the arguments in the error description to hide the sensitive data. The default value is true.

RouterOptions

The command router options.

Timeout

The command router timeout in milliseconds. The default value is 25 seconds. Use Infinite for infinite timeout.

Note: A command route starts at a request to execute the command and ends when the command run is complete or at an error.

TerminalOptions

The terminal configuration options.

Reserved for future.

AuthenticationOptions

🔜 The authentication configuration options.

Planned for next major release.

References