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

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

Содержание

Введение

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

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

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

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

См. подробности в статье 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 не публикует такие параметры в модели и передает код языка автоматически.
DBGate определяет код языка из сегментов URL типа /en/, /en-us/, /en-gb/ или /ru-ru/.
DBGate определяет список языков, настроенных в базе данных, и передает актуальные коды языков.
Например, если настроены языки en и ru, то будут передаваться именно эти значения.
Пример конфигурации содержит имена параметров, используемых в плагине SaveToDB.
TraceSQL
Значение позволяет включить трассировку генерируемых команд SQL.
Значение по умолчанию - false.
StopEnabled
Значение позволяет использовать POST-запросы /app/stop, /app/show, and /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
Значение определяет контекстные параметры, значения которых получаются из процедур SingIn и 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, что позволяет использовать разные модели для покупателей и продавцов.