Настройки приложения DBGate

Содержание

• Введение
• Пример файла конфигурации
• Ключи и секции верхнего уровня
• Общие настройки DBGate
• Настройки подключений

Введение

DBGate читает настройки из JSON-файлов конфигурации, таких как appsettings.json и appsettings.Production.json.

Файл appsettings.json содержит настройки для всех сред, в то время как appsettings.Production.json предназначен для среды Production.

Файл appsettings.json может быть пустым и содержать только {}.

DBGate также поддерживает настройку через переменные среды и параметры командной строки.

См. подробности в статье Configuration in ASP.NET Core.

Пример файла конфигурации

Вот пример файла конфигурации:

{
  "AllowedHosts": "*",
  "Kestrel": {
    "EndPoints": {
      "Http": {
        "Url": "http://localhost:5003"
      }
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      "System": "Information",
      "Microsoft": "Information"
    }
  },
  "DBGate": {
    "Auth": "jwt",
    "WebRoot": "wwwroot",
    "ApiRoot": "api",
    "AppRoot": "app",
    "AuthRoot": "auth",
    "HomeRoot": "home",
    "EditRoots": {
        "edit": "edit.htm"
    },
    "LoginRoots": {
        "login": "login.htm"
    },
    "ApplicationPathBase": null,
    "ConnectionSegment": 0,
    "DefaultPort": 5003,
    "DefaultLanguageFolder": "en-us",
    "AccessTokenExpirationInMinutes": 10,
    "RefreshTokenExpirationInMinutes": 20160,
    "MaxPageSize": 1000,
    "UppercaseNamesInLowercase": true,
    "DefaultContainerName": "default",
    "DisableMetadataCache": false,
    "DisableEditPageCache": false,
    "IncludeAnnotations": true,
    "HideConfigurationObjects": true,
    "HideEditProcedures": true,
    "EnableCodeBrowser": true,
    "BinaryAsHex": false,
    "BigNumbersAsString": false,
    "FunctionPrefixes": "xl_validation_list_, xl_parameter_values_",
    "FunctionSuffixes": "_select",
    "LanguageParameters": "data_language, DataLanguage",
    "TraceSQL": true,
    "StopEnabled": false
  },
  "DBGateW": {
    "WebRoot": "wwwroot",
    "IntegratedSecurityEnabled": false,
    "StopEnabled": true
  },
  "ConnectionStrings": {
    "mssql": {
      "Title": "SQL Server",
      "Offline": false,
      "AllowDatabaseChange": true,
      "AllowServerChange": true,
      "ProviderName": "System.Data.SqlClient",
      "ConnectionString": "Data Source=.\\SQLEXPRESS;Initial Catalog=master;User ID=user;Pwd=pass"
    },
    "pgsql": {
      "Title": "PostgreSQL",
      "Offline": false,
      "AllowDatabaseChange": true,
      "AllowServerChange": true,
      "ProviderName": "Npgsql",
      "ConnectionString": "Server=localhost;Password=pass;User ID=user;Database=postgres"
    },
    "mysql": {
      "Title": "MySQL",
      "Offline": false,
      "AllowDatabaseChange": true,
      "AllowServerChange": true,
      "ProviderName": "MySqlConnector",
      "ConnectionString": "Server=localhost;Password=pass;User ID=user;Database=mysql"
    },
    "mssql-023": {
      "Offline": false,
      "Home": "sample02.htm",
      "QueryList": "",
      "IncludeSchemas": "s02 xls",
      "ExcludeSchemas": null,
      "HideSchemas": "xls",
      "HideConfigurationObjects": true,
      "HideEditProcedures": true,
      "OmitSchemasInNames": "s02",
      "ProviderName": "System.Data.SqlClient",
      "ConnectionString": "Data Source=mssql.savetodb.com;Initial Catalog=AzureDemo100;User ID=sample02_user3;Pwd=Usr_2011#_Xls4168"
    },
    "marketplace": {
      "Title": "Marketplace",
      "Offline": false,
      "OmitSchemasInNames": "marketplace",
      "ApiNameReplacements": {
        "usp_buyer_": "",
        "usp_seller_": ""
      },
      "ProviderName": "MySqlConnector",
      "ConnectionString": "Server=localhost;Password=pass;User ID=user;Database=marketplace",
      "SignIn": "marketplace.usp_sign_in",
      "SignUp": "marketplace.usp_sign_up",
      "SignInRoleField": "role",
      "SignInMessageField": "message",
      "AuthContextValues": {
        "auth_account_id": 1
      },
      "AuthContextParams": "auth_user_id auth_seller_id",
      "RoleUsers": {
        "auth": {
          "Username": "marketplace_auth",
          "Password": "Usr_2011#_Xls4168"
        },
        "default": {
          "QueryList": "marketplace.xl_buyer_views",
          "Username": "marketplace_buyer",
          "Password": "Usr_2011#_Xls4168"
        },
        "buyer": {
          "QueryList": "marketplace.xl_buyer_views",
          "Username": "marketplace_buyer",
          "Password": "Usr_2011#_Xls4168"
        },
        "seller": {
          "QueryList": "marketplace.xl_seller_views",
          "Username": "marketplace_seller",
          "Password": "Usr_2011#_Xls4168"
        }
      }
    }
  }
}

Ключи и секции верхнего уровня

AllowedHosts

Устанавливает разрешенные домены.
См. подробности в статье Host filtering with ASP.NET Core Kestrel web server.
Используйте значение *, чтобы разрешить все адреса.

Kestrel

Конфигурирует веб-сервер Kestrel.
Используйте эту секцию для привязки сертификатов SSL к конечным точкам.
См. подробности в статье Kestrel web server implementation in ASP.NET Core.

Logging

Настраивает протоколирование событий.
См. подробности в статье Logging Configuration.

DBGate

Содержит настройки DBGate.

DBGateW

Содержит настройки, переопределяемые для консольной версии .NET Framework.
Секция может включать только WebRoot, IntegratedSecurityEnabled и StopEnabled.

ConnectionStrings

Определяет имена подключений и их свойства, включая строки подключения.
DBGate использует имена подключений для создания конечных точек.
Для приведенного примера создаются конечные точки: /api/mssql/, /api/pgsql/, /api/mysql/, /api/mssql-023/ и /api/marketplace/.

Общие настройки DBGate

Auth

Устанавливает схему аутентификации.
Возможные значения: jwt и basic.
Значение по умолчанию - jwt, также поддерживается использование обеих схем.

WebRoot

Определяет папку с содержимым веб-сайта.
Значение по умолчанию - wwwroot.

ApiRoot

Определяет корневой сегмент API, например, api в /api/mssql/.
Это значение общее для всех конечных точек.
Значение по умолчанию - api.

AppRoot

Устанавливает корневой сегмент для управления консольным приложением, например, app в /app/stop.
Поддерживаются команды POST: stop, hide и show.
Команды доступны, если StopEnabled равно true.

AuthRoot

Устанавливает корневой сегмент операций JWT, например, auth в /auth/mssql/login.
Поддерживаются команды POST: login, logout, refresh и getToken.

HomeRoot

Устанавливает корневой сегмент перенаправления на домашнюю страницу, например, home в /home/mssql/.
DBGate перенаправляет такие запросы на домашнюю страницу, заданную в свойстве Home подключения, или на сервисный документ, если страница не указана.
Значение по умолчанию - home.

EditRoots

Определяет корневые сегменты страниц редактирования, например, edit в /edit/mssql/, и соответствующие им страницы HTML.
Например, для данной конфигурации, DBGate вернет страницу edit.htm для конечной точки /edit/mssql/.
Значение по умолчанию - edit и страница edit.htm.

LoginRoots

Определяет корневые сегменты страниц ввода имени и пароля, например, login в /login/mssql/, и соответствующие им страницы HTML.
Например, для данной конфигурации, DBGate вернет страницу login.htm для конечной точки /login/mssql/.
Для доступа к этим страницам не требуется предварительная аутентификация.
Значение по умолчанию - login и страница login.htm.

ApplicationPathBase

Устанавливает базовый путь приложения.
Обычно, изменять это значение не требуется.
См. подробности в UsePathBaseExtensions.UsePathBase.

ConnectionSegment

Определяет порядок корневого сегмента API и сегмента подключения.
По умолчанию, DBGate позволяет использовать конечные точки типа /api/mssql/ и /mssql/api/.
Вы можете задать номер сегмента подключения для использования только одного варианта: 2 для /api/mssql/ и 1 для /mssql/api/.
Значение по умолчанию - 0.

DefaultPort

Определяет порт по умолчанию, используемый, если URL не заданы в конфигурации, переменных среды или параметрах командной строки.
Значение по умолчанию - 5003.

DefaultLanguageFolder

Определяет папку языка по умолчанию, используемую для поиска файлов, не найденных в папке заданного языка.
Например, для данной конфигурации, DBGate будет использовать папку en-us.
Значение по умолчанию - en-us.

AccessTokenExpirationInMinutes

Определяет время действия токена доступа в минутах.
Значение по умолчанию - 10 минут.

RefreshTokenExpirationInMinutes

Определяет время действия токена обновления в минутах.
Значение по умолчанию - 20160 минут (14 дней).

MaxPageSize

Устанавливает максимальное количество возвращаемых записей.

UppercaseNamesInLowercase

Определяет преобразование имен объектов и колонок из верхнего регистра в нижний.
Имена со смешанным регистром остаются неизменными.
Значение по умолчанию - true.

DefaultContainerName

Определяет имя контейнера по умолчанию и его схемы для модели.
Контейнер по умолчанию может быть опущен в URL.
Например, для данной конфигурации, конечные точки /api/mssql/ и /api/mssql/default/ будут использовать одну и ту же модель.
Значение по умолчанию - default.

DisableMetadataCache

Отключает кэширование модели базы данных.
Разработчики могут использовать это для загрузки данных модели из базы данных при активной разработке.
Вместо этой опции можно использовать системный параметр URL $reloadMetadata=true или нажимать кнопку Обновить на клиенте с зажатой клавишей Ctrl.
Значение по умолчанию - false.

DisableEditPageCache

Отключает кэширование страниц редактирования.
Разработчики могут использовать это на этапе разработки.
Значение по умолчанию - false.

IncludeAnnotations

Отключает аннотации метаданных по умолчанию.
Встроенный клиент JavaScript не зависит от этой опции.
Значение по умолчанию - true.

HideConfigurationObjects

Скрывает объекты настройки приложений, такие как xls.objects, xls.handlers и другие объекты SaveToDB Framework.
Значение по умолчанию задается в секции DBGate, но может быть переопределено для конкретного подключения.
Значение по умолчанию - true.

HideEditProcedures

Скрывает процедуры сохранения изменений, такие как usp_cashbook2_insert, usp_cashbook2_update и usp_cashbook2_delete для процедуры usp_cashbook2.
DBGate использует такие процедуры для реализации операций POST, PUT и DELETE.
Вы можете опубликовать эти процедуры для прямого вызова методом POST.
Значение по умолчанию задается в секции DBGate, но может быть переопределено для конкретного подключения.
Значение по умолчанию - true.

EnableCodeBrowser

Разрешает получение определения объектов по адресу с конечным сегментом /$definition.
Пользователь должен иметь разрешение VIEW DEFINITION для получения определений.
Значение по умолчанию - false.

BinaryAsHex

Определяет сериализацию двоичных данных по умолчанию в виде HEX-строк вместо base64.
Вместо этой опции можно использовать системный параметр URL $binaryAsHex=true.
Значение по умолчанию - false.

BigNumbersAsString

Определяет сериализацию больших чисел, которые теряют точность в JavaScript, в виде строк.
Вместо этой опции можно использовать системный параметр URL $bigNumbersAsString=true.
Значение по умолчанию - false.

FunctionPrefixes

Содержит список префиксов имен хранимых процедур, которым должен быть присвоен тип FunctionImport вместо ActionImport.
Если DBGate не может определить наличие вывода для процедуры xl_list_users, то будет присвоен тип ActionImport.
Значение по умолчанию - префиксы, используемые в примерах SaveToDB и DBGate.

FunctionSuffixes

Содержит список суффиксов имен хранимых процедур, которым должен быть присвоен тип FunctionImport вместо ActionImport.
Если DBGate не может определить наличие вывода для процедуры usp_users_select, то будет присвоен тип ActionImport.
Значение по умолчанию - суффиксы, используемые в примерах SaveToDB и DBGate.

LanguageParameters

Содержит список имен контекстных параметров языка, разделенных запятой.
DBGate не публикует такие параметры в модели и передает код языка автоматически.
Код языка определяется из сегментов URL типа /en/, /en-us/, /en-gb/ или /ru-ru/.
DBGate определяет список языков, настроенных в базе данных, и передает актуальные коды языков.
Пример конфигурации содержит имена параметров, используемых в плагине SaveToDB.

TraceSQL

Включает трассировку генерируемых команд SQL.
Значение по умолчанию - false.

StopEnabled

Позволяет использовать POST-запросы /app/stop, /app/show, и /app/hide для остановки консольного приложения или отображения и скрытия его окна.
Эти команды могут быть полезны при интеграции DBGate в ваши консольные приложения.
Корень /app можно изменить в свойстве AppRoot.
Значение по умолчанию - false.

IntegratedSecurityEnabled

Разрешает использование аутентификации Windows в подключениях для консольной версии .NET Framework.
Эта версия обычно обслуживает только localhost и запускается в сеансе текущего пользователя, поэтому безопасно разрешить такой вариант аутентификации.
Значение по умолчанию - false.

Настройки подключений

ProviderName

Обязательное значение, определяющее имя провайдера строки подключения.

ConnectionString

Обязательное значение, определяющее строку подключения.
В строке можно использовать существующие логин и пароль пользователей или шаблоны user и pass.
В последнем случае, DBGate запрашивает логин и пароль при подключении пользователя и заменяет шаблоны на полученные значения.

AllowDatabaseChange

Позволяет изменять базу данных подключения непосредственно в URL в формате <connection>:<database>.
Например, можно использовать адрес /edit/mssql:AzureDemo100/ для подключения к базе данных AzureDemo100.
Значение по умолчанию - true для баз данных master, postgres, mysql и false для остальных.

AllowServerChange

Позволяет изменять сервер и базу данных подключения непосредственно в URL в формате <connection>:<server>[,<port>][,<database>].
Например, можно использовать адрес /edit/mssql:mssql.savetodb.com,AzureDemo100/ для подключения к базе данных AzureDemo100 на сервере mssql.savetodb.com.
Значение по умолчанию - false.

AllowPortChange

Позволяет изменять порт непосредственно в URL в формате <connection>:<server>[,<port>][,<database>].
Например, можно использовать адрес /edit/mssql:mssql.savetodb.com,1433,AzureDemo100/ для подключения к базе данных AzureDemo100 на сервере mssql.savetodb.com по порту 1433.
Значение по умолчанию - false.

Title

Позволяет задать заголовок страницы подключения.
Значение по умолчанию - имя подключения.

Offline

Позволяет отключить конечную точку.
DBGate возвращает сообщение о недоступности базы данных даже без обращения к ней.
Значение по умолчанию - false.

Home

Позволяет переопределить домашнюю страницу для подключения.
DBGate использует перенаправление на заданную страницу, когда пользователь нажимает кнопку Домашняя страница.
Чтобы открыть страницу по умолчанию, удерживайте клавишу Ctrl при нажатии кнопки.
Вы можете использовать только имя файла и разместить соответствующие страницы в языковых папках типа en-us и ru-ru. DBGate будет возвращать страницу, соответствующую языку пользователя.
В примере конфигурации выше, в подключении mssql-023 используется страница sample02.htm.

QueryList

Определяет представление списка запросов, используемое для выбора и настройки объектов, публикуемых в сервисном документе.
Используйте это представление для настройки контейнера по умолчанию для вывода только необходимых объектов.
Значение по умолчанию - null, что включает все объекты, доступные пользователю и имеющие вывод.

IncludeSchemas

Определяет явный список схем, разделенных пробелами, которые следует включить в модель.
Если значение пустое, то в модель включаются схемы базы данных для MySQL и все схемы, за исключением указанных в ExcludeSchemas, для остальных серверов.
Чтобы включить все схемы для MySQL, задайте значение *.

ExcludeSchemas

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

HideSchemas

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

HideConfigurationObjects

Скрывает объекты настройки приложений, такие как xls.objects, xls.handlers и другие объекты SaveToDB Framework.
Это значение переопределяет значение по умолчанию из секции DBGate.

HideEditProcedures

Скрывает процедуры сохранения изменений, такие как usp_cashbook2_insert, usp_cashbook2_update и usp_cashbook2_delete для процедуры usp_cashbook2.
DBGate использует такие процедуры для реализации операций POST, PUT и DELETE.
Вы можете опубликовать эти процедуры для прямого вызова методом POST.
Это значение переопределяет значение по умолчанию из секции DBGate.

OmitSchemasInNames

Определяет список схем, разделенных пробелами, которые следует исключить из имен объектов для сервиса.
Например, объекты s02.cashbook и s02.usp_cashbook публикуются по умолчанию как s02_cashbook и s02_usp_cashbook.
В примере конфигурации выше, схема s02 исключается, и объекты будут опубликованы как cashbook и usp_cashbook.
Если значение не задано, схема исключается автоматически, если пользователю доступна только одна схема, не считая схемы xls.
Чтобы отключить эту возможность, задайте любое значение несуществующей схемы, например, none.

ApiNameReplacements

Определяет строки, которые должны быть заменены в именах объектов для сервиса.
В примере конфигурации выше, задана замена строк usp_buyer_ и usp_seller_ на пустые строки.
Соответственно, такие имена как usp_buyer_purchases и usp_seller_orders будут опубликованы как purchases и orders.

SignIn

Определяет хранимую процедуру для аутентификации пользователей.
DBGate выполняет эту процедуру, используя данные пользователя из секции auth в RoleUsers.
Процедура должна иметь минимум два параметра - для имени пользователя и пароля.
Также, процедура может иметь параметры, заданные в секции AuthContextValues.
Процедура должна возвращать минимум одно поле, заданное в свойстве AuthContextParams, обычно это идентификатор пользователя.
Также, процедура может возвращать роль пользователя и сообщение об ошибке в полях, заданных в свойствах SignInRoleField и SignInMessageField.
Если процедура возвращает непустое сообщение, DBGate пробует аутентифицировать пользователя с использованием данных как логина и пароля базы данных.

SignUp

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

SignInRoleField

Определяет имя поля с ролью пользователя в результатах процедур SignIn и SignUp.
DBGate использует значение поля для загрузки данных подключения из соответствующей секции RoleUsers.
Значение по умолчанию - role.

SignInMessageField

Определяет имя поля с сообщением об ошибке в результатах процедур SignIn и SignUp.
Если значение поля не пустое, вызывается исключение, и сообщение возвращается пользователю.
Значение по умолчанию - message.

AuthContextValues

Определяет контекстные параметры и их значения.
Эти параметры не публикуются в модели, но передаются в процедуры с заданными значениями.
Это можно использовать, например, в едином приложении, обслуживающем различные домены (multi-tenant).
В примере конфигурации выше, auth_account_id будет передаваться в процедуры со значением 1.

AuthContextParams

Определяет контекстные параметры, значения которых получаются из процедур SignIn и SignUp.
Эти параметры не публикуются в модели, но передаются в процедуры с заданными значениями.
Обычно, это внутренний идентификатор пользователя, так как обращение к базе данных выполняется под общим пользователем роли.
Однако, можно определить любое количество параметров.
В примере конфигурации выше, приложение определяет два параметра: auth_user_id и auth_seller_id. Процедуры могут использовать один из них или оба.

RoleUsers

Определяет пользователей для каждой роли приложения.
Секция должна содержать определения как минимум для двух встроенных ролей: auth и default.
DBGate использует данные роли auth для выполнения процедур SignIn и SignUp.
DBGate использует данные роли default для выполнения последующих запросов аутентифицированного пользователя, если процедуры SignIn или SignUp не вернули роль, или роль не определена в секции RoleUsers.
Секция роли должна содержать минимум два значения: Username и Password.
Также, в свойстве QueryList можно задать представление (в формате QueryList), которое выводит объекты для сервисного документа.
В примере конфигурации выше, определены роли buyer и seller, что позволяет использовать разные модели для покупателей и продавцов.