Custom commands

Custom commands are one type of Service Fabric command in the CLI. They are usually commands that are either not defined in the Service Fabric Python SDK, or are commands that require a wrapper around or modifications to the SDK.

The most common reasons for requiring a custom command are that the operation requires file I/O, HTTP request modification, or simplification of standard command parameters. For example, the application upload command is a custom command. It sends multiple requests and performs client file I/O.

For more information about the differences between custom and standard commands, see the related documentation.

Custom command files

All custom commands are located in the src/sfctl folder and are in files prefixed by custom_. The commands are split across files that roughly correspond to their command group.

The mapping between command-line syntax and python command line is stored in the src/commands.py file, similar to standard commands.

Tests for custom commands are in their corresponding file under src/sfctl/tests.

Function

First, define the function that performs the command logic in the custom_<target>.py file. Here, <target> refers to the command group name.

For the function signature, include client as the first argument, as the client factory passes this argument into your function upon invocation. For example, here is the function signature for sfctl compose create:

def create_compose_application(client, compose_file, application_id,
                               repo_user=None, encrypted=False,
                               repo_pass=None, timeout=60):

    [...]

    client.create_compose_application(model, timeout)

Here [...] refers to the actual code logic in python.

Mapping

Once the function has been defined, add an additional command under the command group corresponding to your function. For example, here is the mapping for sfctl compose create. Mappings are inside the commands.py file:

with CommandSuperGroup(__name__, self, 'sfctl.custom_app#{}',
                       client_factory=client_create) as super_group:
    with super_group.group('compose') as group:
        group.command('create', 'create_compose_application')

Be sure to check the function namespace, in this case sfctl.custom_app. Also, check if you need to have an API client or not by specifying the client_factory argument.

Test

Once the command has a mapping, be sure to include Nose test cases for the command logic. The tests should be added as functions that include the phrase test at the end of the function name.

All of the unit tests are under the src/sfctl/tests folder.