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

Содержание

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

Введение

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

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

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

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

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

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

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

{
  "AllowedHosts": "*",
  "Kestrel": {
    "EndPoints": {
      "Http": {
        "Url": "http://localhost:5002"
      }
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      "System": "Information",
      "Microsoft": "Information"
    }
  },
  "ODataDB": {
    "Auth": "jwt",
    "WebRoot": "wwwroot",
    "ApiRoot": "v4",
    "AppRoot": "app",
    "AuthRoot": "auth",
    "HomeRoot": "home",
    "EditRoots": {
        "edit": "edit.htm"
    },
    "LoginRoots": {
        "login": "login.htm"
    },
    "ApplicationPathBase": null,
    "ConnectionSegment": 0,
    "DefaultPort": 5002,
    "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
  },
  "ODataDBW": {
    "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.

ODataDB

Секция с настройками ODataDB.

ODataDBW

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

ConnectionStrings

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

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

Auth

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

WebRoot

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

ApiRoot

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

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/.
ODataDB перенаправляет такие запросы на домашнюю страницу, заданную в свойстве Home подключения, или на сервисный документ, если страница не задана.
По умолчанию — home.

EditRoots

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

LoginRoots

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

ApplicationPathBase

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

ConnectionSegment

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

DefaultPort

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

DefaultLanguageFolder

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

AccessTokenExpirationInMinutes

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

RefreshTokenExpirationInMinutes

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

MaxPageSize

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

UppercaseNamesInLowercase

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

DefaultContainerName

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

DisableMetadataCache

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

DisableEditPageCache

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

IncludeAnnotations

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

HideConfigurationObjects

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

HideEditProcedures

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

EnableCodeBrowser

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

BinaryAsHex

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

BigNumbersAsString

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

FunctionPrefixes

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

FunctionSuffixes

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

LanguageParameters

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

TraceSQL

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

StopEnabled

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

IntegratedSecurityEnabled

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

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

ProviderName

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

ConnectionString

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

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

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

Home

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

QueryList

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

IncludeSchemas

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

ExcludeSchemas

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

HideSchemas

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

HideConfigurationObjects

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

HideEditProcedures

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

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

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

SignUp

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

SignInRoleField

Указывает имя поля с ролью пользователя в результатах процедур SignIn и SignUp.
ODataDB использует значение этого поля для загрузки данных подключения из соответствующей секции 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.
ODataDB использует данные роли auth для выполнения процедур SignIn и SignUp.
Данные роли default используются для выполнения последующих запросов аутентифицированного пользователя, если процедуры SignIn или SignUp не вернули роль, или роль не определена в секции RoleUsers.
Секция роли должна содержать минимум два значения: Username и Password.
Также в свойстве QueryList можно задать представление (в формате QueryList), которое выводит объекты для сервисного документа.
В приведенной конфигурации определены роли buyer и seller, что позволяет использовать разные модели для покупателей и продавцов.