Поделиться через

Создание поставщика баз данных

Сведения о написании поставщика базы данных Entity Framework Core см. в статье "Поэтому вы хотите написать поставщик EF Core" Артуром Vickers.

Примечание.

Эти записи не были обновлены с тех пор, как EF Core 1.1, и с этого времени произошли значительные изменения. Проблема 681 — отслеживание обновлений этой документации.

База кода EF Core открытый код и содержит несколько поставщиков баз данных, которые можно использовать в качестве ссылки. Исходный код можно найти по адресу https://github.com/dotnet/efcore. Также может быть полезно ознакомиться с кодом для часто используемых сторонних поставщиков, таких как Npgsql, Pomelo MySQL и SQL Server Compact. В частности, эти проекты настраиваются для расширения и запуска функциональных тестов, которые мы публикуем в NuGet. Этот вид установки настоятельно рекомендуется.

Актуальность изменений поставщика

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

До 2.1 мы использовали providers-beware и метки для проблем с GitHub и providers-fyi запросы на вытягивание для аналогичной цели. Мы будем продолжать использовать эти метки для проблем, чтобы указать, какие рабочие элементы в данном выпуске также могут потребовать выполнения работы в поставщиках. providers-beware Метка обычно означает, что реализация рабочего элемента может нарушить поставщиков, а providers-fyi метка обычно означает, что поставщики не будут нарушены, но код может потребоваться изменить в любом случае, например, чтобы включить новые функции.

Предлагаемое именование сторонних поставщиков

Мы рекомендуем использовать следующее именование для пакетов NuGet. Это соответствует именам пакетов, доставленных командой EF Core.

<Optional project/company name>.EntityFrameworkCore.<Database engine name>

Например:

  • Microsoft.EntityFrameworkCore.SqlServer
  • Npgsql.EntityFrameworkCore.PostgreSQL
  • EntityFrameworkCore.SqlServerCompact40

Тесты спецификации EF Core

EF Core предоставляет проект набора тестов спецификаций, который рекомендуется реализовать всем поставщикам. Проект содержит тесты, которые обеспечивают правильную работу поставщика, например путем выполнения различных запросов LINQ и обеспечения возврата правильных результатов. Этот набор тестов используется собственными поставщиками EF Core (например, SQL Server, SQLite и Azure Cosmos DB) в качестве основного механизма тестирования регрессии и постоянно обновляется и улучшается при добавлении новых функций в EF Core. Реализуя эти тесты для других сторонних поставщиков, вы можете убедиться, что поставщик базы данных работает правильно и реализует все последние функции EF Core. Обратите внимание, что набор тестов довольно велик, так как он охватывает весь набор функций EF Core; Вам не нужно реализовать все - это идеально хорошо, чтобы выбрать определенные тестовые классы, и постепенно улучшить покрытие с течением времени.

Чтобы начать использование тестов спецификации, выполните следующие действия.

  • Создайте тестовый проект xUnit в решении поставщика. Мы предлагаем имя <Provider>.FunctionalTests для согласованности, поэтому если ваш поставщик вызывается AcmeSoftware.EntityFramework.AcmeDb, вызовите тестовый проект AcmeSoftware.EntityFramework.AcmeDb.FunctionalTests.
  • В новом тестовом проекте обратитесь к тестам спецификации EF, которые публикуются как обычные пакеты Nuget. Для реляционных поставщиков набор тестов спецификации — Microsoft.EntityFrameworkCore.Relational.Specification.Tests для нереляционного поставщика, используйте Microsoft.EntityFrameworkCore.Specification.Tests).
  • Выберите тестовый класс из тестов спецификации EF и расширьте его из соответствующего тестового класса в собственном проекте. Доступные тестовые классы можно увидеть в исходном коде EF. Класс должен быть назван на основе тестового класса EF с именем поставщика, вставленным в соответствующее место. Например, NorthwindWhereQueryRelationalTestBase (что является хорошим местом для начала), будет расширено NorthwindWhereQueryAcmeDbTest.
  • В самом начале вы будете иметь немного тестовой инфраструктуры для реализации - как только это сделать один раз, все станет проще. Например, для NorthwindWhereQueryAcmeDbTest реализации NorthwindWhereQueryAcmeDbFixtureпотребуется сценарий Northwind.sql для заполнения версии AcmeDb базы данных Northwind.sql.AcmeDbNorthwindTestStoreFactory Мы настоятельно рекомендуем сохранить рядом набор тестов другого поставщика EF Core и следить за тем, что он делает. Например, реализация тестов спецификации SQL Server отображается здесь.
  • После завершения инфраструктуры для тестового класса вы начнете видеть некоторые зеленые тесты. Вы можете исследовать неудачные тесты или временно пропустить их для последующего исследования. Таким образом можно добавить все больше и больше тестового класса.
  • В какой-то момент, когда вы расширили большую часть вышестоящий тестовых классов, можно также создатьAcmeDbComplianceTest, что расширяетсяRelationalComplianceTestBase. Этот тестовый класс завершится ошибкой, если собственный тестовый проект не расширяет тестовый класс EF Core. Это отличный способ узнать, завершен ли набор тестов, а также добавить ли EF новый тестовый класс в новую версию. Вы также можете отказаться от расширения определенных тестовых классов, если они не готовы (или не нужны).

Утверждения SQL

При реализации тестов спецификации у вас есть возможность дополнительно утверждать SQL, который производит EF Core. Это не обязательно: реализация теста спецификации уже проверка, которые поставщик вернул ожидаемые строки из базы данных, поэтому, если он проходит, поставщик, скорее всего, выполняет правильные действия. Тем не менее, утверждая, что SQL — это то, что вы ожидаете, что оно может быть добавлено дополнительное покрытие в некоторых случаях, особенно в тех случаях, когда используется некоторые конструкции SQL, относящиеся к вашей базе данных.

Например, вот тест в тестовом Where_simple классе NorthwindWhereQuerySqlServerTest:

public override async Task Where_simple(bool async)
{
    await base.Where_simple(async);

    AssertSql(
        @"SELECT [c].[CustomerID], [c].[Address], [c].[City], [c].[CompanyName], [c].[ContactName], [c].[ContactTitle], [c].[Country], [c].[Fax], [c].[Phone], [c].[PostalCode], [c].[Region]
FROM [Customers] AS [c]
WHERE [c].[City] = N'London'");
}

Базовый вызов выполняет проверку спецификации, которая выполняет запрос LINQ и проверяет правильность результатов. Кроме того, гарантирует, AssertSql что SQL соответствует базовому плану, включенном в тест.

Проверка сбоев утверждения SQL

Если утверждение SQL завершается ошибкой, xunit обычно сообщает только фрагмент SQL, который не совпадал. Чтобы просмотреть полный SQL, созданный поставщиком, можно получить вывод тестовой инфраструктуры полный новый базовый план при сбое теста, чтобы можно было проверить его и, возможно, заменить старый. Для этого передайте предоставленный ITestOutputHelper xunit TestSqlLoggerFactory в тестовый светильник:

public NorthwindWhereQuerySqlServerTest(
    NorthwindQuerySqlServerFixture<NoopModelCustomizer> fixture,
    ITestOutputHelper testOutputHelper)
    : base(fixture)
{
    ClearLog();
    Fixture.TestSqlLoggerFactory.SetTestOutputHelper(testOutputHelper);
}

В наборах тестов EF Core мы обычно сохраняем указанные выше строковый комментарий в конструкторе, чтобы мы могли легко раскомментировать его в любой момент, когда утверждение SQL завершается сбоем.

Массовое обновление базовых показателей

Если вы используете утверждения SQL много, в наборе тестов будет много базовых показателей SQL. В некоторых случаях небольшое изменение ( в поставщике или в самом EF Core) может привести к сбою большого количества этих утверждений по какой-либо причине, например, скобки были добавлены где-то. В этом случае исправление всех затронутых базовых показателей вручную может быть очень емким и трудоемким процессом.

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