Бөлісу құралы:

Руководство по проектированию

В следующих разделах приведены рекомендации по проектированию интерфейса командной строки. Думайте о том, что приложение ожидает в командной строке, как и то, что ожидает сервер REST API в URL-адресе. Согласованные правила rest API — это то, что делает их доступными для разработчиков клиентских приложений. Таким же образом пользователи приложений командной строки будут иметь лучший интерфейс, если дизайн ИНТЕРФЕЙСА командной строки соответствует общим шаблонам.

После создания интерфейса командной строки его трудно изменить, особенно если пользователи использовали интерфейс командной строки в сценариях, которые они ожидают продолжать работать.

Символы

Команды и подкоманды

Если команда имеет подкоманды, команда должна функционировать в качестве категории или идентификатора группировки для подкоманд, а не указывать действие. При вызове приложения укажите команду группирования и одну из ее подкомандах. Например, попробуйте выполнить dotnet toolи вы получите сообщение об ошибке, так как tool команда определяет только группу вложенных команд, связанных с инструментом, например install и list. Вы можете запустить dotnet tool install, но dotnet tool само по себе будет неполным.

Определение областей помогает пользователям, потому что это организует выходные данные справки.

В интерфейсе командной строки часто существует неявная область. Например, в .NET CLI неявная область — это проект, а в интерфейсе командной строки Docker — образ. В результате можно использовать dotnet build без указания области. Рассмотрите, имеет ли интерфейс командной строки неявную область. Если это делается, рассмотрите, следует ли разрешить пользователю дополнительно включить или опустить его, как в docker build и docker image build. Если вы по желанию разрешаете пользователю вводить неявную зону, то автоматически получаете поддержку и автозаполнение табуляции для этой группировки команд. Укажите необязательное использование неявной группы, определив две команды, которые выполняют одну и ту же операцию.

Опции в качестве параметров

Опции должны предоставлять параметры командам, а не указывать сами действия. Это рекомендуемый принцип проектирования, хотя он не всегда соблюдается System.CommandLine (--help отображает справочную информацию).

Именование

Псевдонимы в краткой форме

Как правило, рекомендуется свести к минимуму количество псевдонимов параметра short-form, которые вы определили.

В частности, избегайте использования любого из следующих псевдонимов, отличных от общего использования в .NET CLI и других приложениях командной строки .NET:

  • -i для --interactive.

    Этот параметр сигнализирует пользователю о том, что им может быть предложено ввести входные данные, чтобы ответить на вопросы, необходимые команде. Например, запрос имени пользователя. Интерфейс командной строки может использоваться в сценариях, поэтому используйте осторожность при появлении запроса пользователей, которые не указали этот параметр.

  • -o для --output.

    Некоторые команды создают файлы в результате их выполнения. Этот параметр следует использовать для определения расположения этих файлов. В случаях, когда создается один файл, этот параметр должен быть путь к файлу. В случаях, когда создается множество файлов, этот параметр должен быть путь к каталогу.

  • -v для --verbosity.

    Команды часто предоставляют выходные данные пользователю в консоли; этот параметр используется для указания объема выходных данных, отправляемых пользователем. Дополнительные сведения см. в разделе "Вариант--verbosity" далее в этой статье.

Существуют также некоторые псевдонимы с общим использованием, ограниченными интерфейсом командной строки .NET. Эти псевдонимы можно использовать для других вариантов в приложениях, но помните о возможности путаницы.

  • -c для --configuration

    Этот параметр часто ссылается на именованную конфигурацию сборки, например Debug или Release. Вы можете использовать любое имя для конфигурации, но большинство инструментов ожидают одно из предложенных. Этот параметр часто используется для настройки других свойств таким образом, чтобы это имело смысл для данной конфигурации — например, при сборке конфигурации Debug выполняется меньше оптимизации кода. Рассмотрите этот параметр, если команда имеет разные режимы работы.

  • -f для --framework

    Этот параметр используется для выбора одного моникера Целевой платформы (TFM), поэтому если приложение CLI имеет разное поведение в зависимости от выбранного TFM, следует поддерживать этот флаг.

  • -p для --property

    Если приложение в конечном итоге вызывает MSBuild, пользователю часто потребуется настроить этот вызов каким-то образом. Этот параметр позволяет предоставлять свойства MSBuild в командной строке и передавать их в базовый вызов MSBuild. Если ваше приложение не использует MSBuild, но требует набор ключей и значений, рекомендуется использовать то же имя параметра, чтобы учесть ожидания пользователей.

  • -r для --runtime

    Если приложение может работать в разных средах выполнения или имеет логику, зависящей от среды выполнения, рассмотрите возможность поддержки этого параметра в качестве способа указания идентификатора среды выполнения. Если ваше приложение поддерживает --runtime, рассмотрите возможность поддержки --os , а --arch также. Эти параметры позволяют указывать только части ОС или архитектуры RID, оставляя неуказанную часть определяться на основе текущей платформы. Дополнительные сведения см. в разделе dotnet publish.

Краткие имена

Создайте имена для команд, параметров и аргументов как можно короче и проще для написания. Например, если class достаточно ясно, не сделайте команду classification.

Строчные названия

Определите имена только в нижнем регистре, за исключением того, что можно сделать псевдонимы верхнего регистра, чтобы сделать команды или параметры нечувствительными.

Имена регистров Kebab

Используйте кебаб-кейс, чтобы различать слова. Например: --additional-probing-path.

Плюрализация

В приложении соблюдайте согласованность в использовании множественного числа. Например, не смешивайте множественные и единичные названия для параметров, которые могут иметь несколько значений (максимальная кратность больше единицы):

Имена опций Согласованность
--additional-probing-paths и --sources. ✔️
--additional-probing-path и --source. ✔️
--additional-probing-paths и --source. ❌
--additional-probing-path и --sources. ❌

Глаголы и существительные

Используйте глаголы, а не существительные для команд, обозначающих действия (без подкоманд под ними), например: dotnet workload remove, а не dotnet workload removal. И используйте существительные, а не глаголы для параметров, например: --configuration, а не --configure.

Параметр --verbosity

System.CommandLine Приложения обычно предлагают параметр, указывающий --verbosity , сколько выходных данных отправляется в консоль. Ниже приведены стандартные пять параметров:

  • Q[uiet]
  • M[inimal]
  • N[ormal]
  • D[etailed]
  • Diag[nostic]

Это стандартные имена, но существующие приложения иногда используют Silent вместо Quiet, а Trace, Debug или Verbose вместо Diagnostic.

Каждое приложение определяет собственные критерии, определяющие, что отображается на каждом уровне. Как правило, приложению требуется только три уровня:

  • Тихий
  • Нормальный
  • Диагностика

Если приложению не требуется пять разных уровней, параметр по-прежнему должен определять те же пять параметров. В этом случае Minimal и Normal будут производить те же выходные данные, а Detailed и Diagnostic также будут такими же. Это позволяет вашим пользователям просто вводить то, с чем они знакомы, и будет выбран наиболее подходящий вариант.

Ожидается, что Quiet не выводит данные на консоль. Однако если приложение предлагает интерактивный режим, приложение должно выполнить одно из следующих действий:

  • Отображение запросов на ввод данных, когда --interactive указано, даже если --verbosity — Quiet.
  • Запретить использование --verbosity Quiet и --interactive вместе.

В противном случае приложение будет ожидать ввода, не сообщая пользователю, что он ожидает. Появится, что приложение заморозится, и пользователь не будет иметь представления о том, что приложение ожидает входных данных.

Если вы определяете псевдонимы, используйте -v для --verbosity и сделайте -v без аргумента псевдонимом для --verbosity Diagnostic. Используйте -q для --verbosity Quiet.

Соглашения .NET CLI и POSIX

Интерфейс командной строки .NET не соответствует всем соглашениям POSIX.

Двойной дефис

Несколько команд в .NET CLI имеют специальную реализацию маркера двойного дефиса. В случае dotnet run, dotnet watch и dotnet tool run маркеры, следующие за --, передаются в приложение, запускаемое командой. Рассмотрим пример.

dotnet run --project ./myapp.csproj -- --message "Hello world!"
                                    ^^

В этом примере --project параметр передается в команду dotnet run, а --message параметр с аргументом передается в качестве параметра командной строки myapp при запуске.

Маркер -- не всегда требуется для передачи параметров в приложение, которое выполняется с помощью dotnet run. Без двойного дефиса команда dotnet run автоматически передает опции в приложение, если они не распознаются как относящиеся к dotnet run или MSBuild. Поэтому следующие командные строки эквивалентны, так как dotnet run не распознает аргументы и параметры:

dotnet run -- quotes read --delay 0 --fg-color red
dotnet run quotes read --delay 0 --fg-color red

Пропуск разделителя между параметрами и аргументами

Интерфейс командной строки .NET не поддерживает соглашение POSIX, которое позволяет опустить разделитель при указании псевдонима однозначного параметра.

Несколько аргументов без повторения имени параметра

Интерфейс командной строки .NET не принимает несколько аргументов для одного параметра, не повторяя имя параметра.

Булевые параметры

В .NET CLI некоторые булевые параметры ведут себя одинаково при передаче false, так же как и при передаче true. Это поведение приводит к тому, что код .NET CLI, реализующий параметр, проверяет наличие или отсутствие параметра, игнорируя значение. Примером команды --no-restore является dotnet build. При передаче --no-restore false операция восстановления будет пропущена так же, как при указании --no-restore true или --no-restore.

Кебаб случай

В некоторых случаях .NET CLI не использует стиль kebab case для имен команд, параметров или аргументов. Например, есть параметр .NET CLI, который называется --additionalprobingpath вместо --additional-probing-path.

См. также

  • Last updated on