Настройки приложения 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, что позволяет использовать разные модели для покупателей и продавцов.