Extensible Storage Engine (ESE) в Windows через PowerShell

Что такое ESE (Extensible Storage Engine)?

ESE (также известная как JET Blue) — это встроенная в Windows высокопроизводительная, транзакционная NoSQL база данных, используемая:

• Active Directory (NTDS.dit)
• Exchange Server
• Windows Search
• Windows Update
• Почтовые клиенты

Особенности:

• ISAM (Indexed Sequential Access Method) база данных
• B-деревья для индексов
• Поддержка транзакций с откатом
• Встроенное сжатие
• Журналирование Write-Ahead Logging

Архитектура ESE

graph TB
    A[PowerShell/C# App] --> B[Managed ESE Interop]
    B --> C[Esent.dll - Native API]
    C --> D[ESE Runtime]

    subgraph "ESE Components"
        D --> E[Transaction Manager]
        D --> F[Version Store]
        D --> G[Buffer Manager]
        D --> H[Log Manager]
    end

    E --> I[Database File .edb]
    F --> I
    G --> I
    H --> J[Transaction Logs .log]

    I --> K[Checkpoint File .chk]
    J --> K

    style A fill:#e1f5fe
    style I fill:#f3e5f5
    style J fill:#fff3e0

Доступные API для PowerShell

1. Microsoft.Isam.Esent.Interop (Управляемый .NET API)

# Требует .NET Framework 4.7.2+ 
# В PowerShell 7.5 работает ТОЛЬКО в Windows PowerShell Compatibility Mode

# Установка через NuGet
Install-Package Microsoft.Database.Isam -ProviderName NuGet

# Или загрузка сборки из GAC
Add-Type -AssemblyName "Microsoft.Isam.Esent.Interop"

2. EsentPowershell Module (Сообщество)

# Экспериментальный модуль
Install-Module -Name EsentPowershell -AllowPrerelease

# Пример использования
Import-Module EsentPowershell

3. P/Invoke напрямую в esent.dll

Add-Type -TypeDefinition @"
using System;
using System.Runtime.InteropServices;

public class EsentNative {
    [DllImport("esent.dll", CharSet = CharSet.Unicode)]
    public static extern int JetCreateInstance(
        out IntPtr ppinstance,
        string szInstanceName
    );

    [DllImport("esent.dll")]
    public static extern int JetInit(ref IntPtr pinstance);

    [DllImport("esent.dll")]
    public static extern int JetTerm(IntPtr instance);

    // ... и более 200 других функций
}
"@

Полный пример работы с ESE через PowerShell

Установка и настройка окружения

# 1. Скачиваем NuGet пакет вручную (т.к. в PS7.5 нет прямого доступа к .NET Framework NuGet)
$packageSource = "https://www.nuget.org/api/v2/package/Microsoft.Database.Isam/1.0.0"
$tempDir = Join-Path $env:TEMP "EsentPackage"
New-Item -ItemType Directory -Path $tempDir -Force

# 2. Скачиваем и распаковываем
Invoke-WebRequest -Uri $packageSource -OutFile "$tempDir\package.nupkg"
Expand-Archive -Path "$tempDir\package.nupkg" -DestinationPath "$tempDir\extracted"

# 3. Загружаем сборки
Add-Type -Path "$tempDir\extracted\lib\net45\Microsoft.Isam.Esent.Interop.dll"
Add-Type -Path "$tempDir\extracted\lib\net45\Microsoft.Database.Isam.dll"

# 4. Проверяем загрузку
[AppDomain]::CurrentDomain.GetAssemblies() | 
    Where-Object {$_.FullName -like "*Esent*"} | 
    Select-Object FullName

Создание базы данных и таблиц

using namespace Microsoft.Isam.Esent.Interop

class EsentDatabase {
    [Instance]$Instance
    [Session]$Session
    [string]$DatabasePath

    EsentDatabase([string]$dbPath) {
        $this.DatabasePath = $dbPath
        $this.Initialize()
    }

    [void]Initialize() {
        # Создаем экземпляр ESE
        $this.Instance = [Instance]::new("MyEsentInstance")

        # Настройка параметров
        $this.Instance.Parameters.CreatePathIfNotExist = $true
        $this.Instance.Parameters.TempDirectory = "C:\temp\esent"
        $this.Instance.Parameters.SystemDirectory = "C:\temp\esent"
        $this.Instance.Parameters.LogFileDirectory = "C:\temp\esent\logs"
        $this.Instance.Parameters.BaseName = "MyDb"
        $this.Instance.Parameters.LogFileSize = 1024  # 1MB
        $this.Instance.Parameters.MaxVerPages = 1024
        $this.Instance.Parameters.MaxSessions = 32

        # Включаем сжатие
        $this.Instance.Parameters.EnableIndexChecking = $true
        $this.Instance.Parameters.CacheSizeMax = 16 * 1024 * 1024  # 16MB кэша

        $this.Instance.Init()

        # Создаем сессию
        $this.Session = [Session]::new($this.Instance)
    }

    [void]CreateDatabase() {
        $dbid = [JET_DBID]::Nil

        # Создаем или открываем базу данных
        if (-not (Test-Path $this.DatabasePath)) {
            [Api]::JetCreateDatabase(
                $this.Session,
                $this.DatabasePath,
                "",
                [ref]$dbid,
                [CreateDatabaseGrbit]::None
            )
            Write-Host "База данных создана: $($this.DatabasePath)"
        } else {
            [Api]::JetAttachDatabase(
                $this.Session,
                $this.DatabasePath,
                [AttachDatabaseGrbit]::None
            )
            [Api]::JetOpenDatabase(
                $this.Session,
                $this.DatabasePath,
                "",
                [ref]$dbid,
                [OpenDatabaseGrbit]::None
            )
            Write-Host "База данных открыта: $($this.DatabasePath)"
        }

        # Всегда закрываем базу
        [Api]::JetCloseDatabase($this.Session, $dbid, [CloseDatabaseGrbit]::None)
    }

    [void]CreateTable([string]$tableName, [hashtable]$columns) {
        $dbid = [JET_DBID]::Nil
        [Api]::JetOpenDatabase(
            $this.Session,
            $this.DatabasePath,
            "",
            [ref]$dbid,
            [OpenDatabaseGrbit]::None
        )

        # Начинаем транзакцию
        [Api]::JetBeginTransaction($this.Session)

        try {
            # Создаем таблицу
            $tableid = [JET_TABLEID]::Nil
            [Api]::JetCreateTable(
                $this.Session,
                $dbid,
                $tableName,
                1,  # Initial pages
                100, # Density
                [ref]$tableid
            )

            # Добавляем колонки
            foreach ($col in $columns.GetEnumerator()) {
                $colName = $col.Key
                $colType = $col.Value

                $columndef = switch ($colType) {
                    "Long" { 
                        [ColumnDefinition]::new(
                            $colName,
                            [JET_coltyp]::Long,
                            [ColumnDefinitionGrbit]::ColumnFixed
                        )
                    }
                    "Text" {
                        [ColumnDefinition]::new(
                            $colName,
                            [JET_coltyp]::LongText,
                            [ColumnDefinitionGrbit]::ColumnTagged
                        )
                    }
                    "Binary" {
                        [ColumnDefinition]::new(
                            $colName,
                            [JET_coltyp]::LongBinary,
                            [ColumnDefinitionGrbit]::ColumnTagged
                        )
                    }
                    default {
                        [ColumnDefinition]::new(
                            $colName,
                            [JET_coltyp]::LongText,
                            [ColumnDefinitionGrbit]::ColumnTagged
                        )
                    }
                }

                $columnid = [JET_COLUMNID]::Nil
                [Api]::JetAddColumn(
                    $this.Session,
                    $tableid,
                    $columndef,
                    $null,
                    0,
                    [ref]$columnid
                )
            }

            # Создаем первичный индекс
            [Api]::JetCreateIndex(
                $this.Session,
                $tableid,
                "PrimaryIndex",
                [CreateIndexGrbit]::IndexPrimary,
                "+Id\0\0"
            )

            [Api]::JetCloseTable($this.Session, $tableid)
            [Api]::JetCommitTransaction($this.Session, [CommitTransactionGrbit]::LazyFlush)

            Write-Host "Таблица '$tableName' создана"
        }
        catch {
            [Api]::JetRollback($this.Session, [RollbackTransactionGrbit]::None)
            throw
        }
        finally {
            [Api]::JetCloseDatabase($this.Session, $dbid, [CloseDatabaseGrbit]::None)
        }
    }

    [void]InsertData([string]$tableName, [hashtable]$data) {
        $dbid = [JET_DBID]::Nil
        [Api]::JetOpenDatabase(
            $this.Session,
            $this.DatabasePath,
            "",
            [ref]$dbid,
            [OpenDatabaseGrbit]::None
        )

        $tableid = [JET_TABLEID]::Nil
        [Api]::JetOpenTable(
            $this.Session,
            $dbid,
            $tableName,
            $null,
            0,
            [OpenTableGrbit]::None,
            [ref]$tableid
        )

        [Api]::JetBeginTransaction($this.Session)

        try {
            # Подготавливаем вставку
            [Api]::JetPrepareUpdate(
                $this.Session,
                $tableid,
                [JET_prep]::Insert
            )

            # Заполняем колонки
            foreach ($item in $data.GetEnumerator()) {
                $columnid = [Api]::GetTableColumnid(
                    $this.Session,
                    $tableid,
                    $item.Key
                )

                if ($item.Value -is [int]) {
                    [Api]::JetSetColumn(
                        $this.Session,
                        $tableid,
                        $columnid,
                        [ref]$item.Value,
                        [System.Runtime.InteropServices.Marshal]::SizeOf([int]),
                        [SetColumnGrbit]::None,
                        $null
                    )
                }
                elseif ($item.Value -is [string]) {
                    $bytes = [System.Text.Encoding]::Unicode.GetBytes($item.Value)
                    [Api]::JetSetColumn(
                        $this.Session,
                        $tableid,
                        $columnid,
                        $bytes,
                        $bytes.Length,
                        [SetColumnGrbit]::None,
                        $null
                    )
                }
            }

            # Выполняем вставку
            [Api]::JetUpdate($this.Session, $tableid)
            [Api]::JetCommitTransaction($this.Session, [CommitTransactionGrbit]::LazyFlush)

            Write-Host "Данные вставлены в '$tableName'"
        }
        catch {
            [Api]::JetRollback($this.Session, [RollbackTransactionGrbit]::None)
            throw
        }
        finally {
            [Api]::JetCloseTable($this.Session, $tableid)
            [Api]::JetCloseDatabase($this.Session, $dbid, [CloseDatabaseGrbit]::None)
        }
    }

    [array]ReadData([string]$tableName, [int]$limit = 100) {
        $results = @()
        $dbid = [JET_DBID]::Nil

        [Api]::JetOpenDatabase(
            $this.Session,
            $this.DatabasePath,
            "",
            [ref]$dbid,
            [OpenDatabaseGrbit]::None
        )

        $tableid = [JET_TABLEID]::Nil
        [Api]::JetOpenTable(
            $this.Session,
            $dbid,
            $tableName,
            $null,
            0,
            [OpenTableGrbit]::None,
            [ref]$tableid
        )

        [Api]::JetMove($this.Session, $tableid, [JET_Move]::First, [MoveGrbit]::None)

        $count = 0
        do {
            $record = @{}

            # Получаем список колонок
            $columnList = [Api]::GetTableColumnInfo($this.Session, $tableid, [ColumnInfoList]::All)

            foreach ($col in $columnList) {
                $buffer = $null
                $actualSize = 0

                # Определяем тип данных
                if ($col.Coltyp -eq [JET_coltyp]::Long) {
                    $buffer = 0
                    [Api]::JetRetrieveColumn(
                        $this.Session,
                        $tableid,
                        $col.Columnid,
                        [ref]$buffer,
                        [System.Runtime.InteropServices.Marshal]::SizeOf([int]),
                        [ref]$actualSize,
                        [RetrieveColumnGrbit]::None,
                        $null
                    )
                    $record[$col.Name] = $buffer
                }
                elseif ($col.Coltyp -eq [JET_coltyp]::LongText) {
                    $buffer = New-Object byte[] 4096
                    [Api]::JetRetrieveColumn(
                        $this.Session,
                        $tableid,
                        $col.Columnid,
                        $buffer,
                        $buffer.Length,
                        [ref]$actualSize,
                        [RetrieveColumnGrbit]::None,
                        $null
                    )
                    $record[$col.Name] = [System.Text.Encoding]::Unicode.GetString($buffer, 0, $actualSize).TrimEnd("`0")
                }
            }

            $results += [PSCustomObject]$record
            $count++

        } while (
            [Api]::JetMove($this.Session, $tableid, [JET_Move]::Next, [MoveGrbit]::None) -eq 0 -and 
            $count -lt $limit
        )

        [Api]::JetCloseTable($this.Session, $tableid)
        [Api]::JetCloseDatabase($this.Session, $dbid, [CloseDatabaseGrbit]::None)

        return $results
    }

    [void]Dispose() {
        if ($this.Session -ne $null) {
            $this.Session.Dispose()
        }
        if ($this.Instance -ne $null) {
            $this.Instance.Dispose()
        }
    }
}

# Использование
try {
    $db = [EsentDatabase]::new("C:\Data\MyDatabase.edb")
    $db.CreateDatabase()

    # Создаем таблицу
    $columns = @{
        "Id" = "Long"
        "Name" = "Text"
        "Email" = "Text"
        "Created" = "Long"
    }
    $db.CreateTable("Users", $columns)

    # Вставляем данные
    $data = @{
        "Id" = 1
        "Name" = "Иван Петров"
        "Email" = "ivan@example.com"
        "Created" = [DateTime]::Now.Ticks
    }
    $db.InsertData("Users", $data)

    # Читаем данные
    $users = $db.ReadData("Users", 10)
    $users | Format-Table
}
finally {
    $db.Dispose()
}

Процесс работы ESE

sequenceDiagram
    participant P as PowerShell
    participant M as Managed API
    participant N as Esent.dll
    participant E as ESE Engine
    participant D as Disk

    P->>M: JetCreateInstance()
    M->>N: JetCreateInstance()
    N->>E: Создать экземпляр
    E-->>N: Успех
    N-->>M: Успех
    M-->>P: Экземпляр создан

    P->>M: JetInit()
    M->>N: JetInit()
    N->>E: Инициализировать
    E->>D: Создать файлы (edb, log)
    E-->>N: Успех
    N-->>M: Успех
    M-->>P: Инициализация завершена

    P->>M: JetBeginTransaction()
    M->>N: JetBeginTransaction()
    N->>E: Начать транзакцию
    E->>F: Создать версию

    P->>M: JetInsert()
    M->>N: JetInsert()
    N->>E: Вставить запись
    E->>B: Добавить в буфер
    E->>L: Записать в лог

    P->>M: JetCommitTransaction()
    M->>N: JetCommitTransaction()
    N->>E: Зафиксировать
    E->>D: Записать на диск
    E->>C: Создать checkpoint
    E-->>N: Успех
    N-->>M: Успех
    M-->>P: Транзакция завершена

Плюсы ESE

Преимущества:

1. Высокая производительность: Оптимизирована для операций вставки/чтения

• 50,000+ операций в секунду на обычном HDD
• 200,000+ операций на SSD

1. Встроенность в Windows: Не требует установки

• Доступна на всех версиях Windows
• Автоматические обновления с ОС

1. Надёжность: Промышленный уровень

• ACID-транзакции
• Автоматическое восстановление после сбоев
• Write-Ahead Logging

1. Эффективное использование памяти:

• Кэширование с LRU алгоритмом
• Memory-mapped файлы
• Динамическое управление памятью

1. Безопасность:

• Встроенное шифрование
• Поддержка Windows Security
• Контроль доступа на уровне ОС

Минусы и ограничения

Недостатки:

1. Сложность API: Низкоуровневый C-стиль API

• Более 250 функций
• Требует ручного управления ресурсами

1. Ограниченная документация:

• Документация ориентирована на C/C++
• Мало примеров для .NET
• Отсутствуют PowerShell примеры

1. Проблемы с PowerShell 7.5:

• Требует Windows PowerShell Compatibility Session
• Нет официальной поддержки .NET Core
• Ограниченная отладка

1. Отсутствие ORM:

• Нет Entity Framework провайдера
• Нет LINQ поддержки
• Ручное маппинг типов данных

1. Только для Windows:

• Нет поддержки Linux/macOS
• Зависит от Win32 API

Сравнение производительности

Оптимизация производительности

# Оптимальные параметры для высокой нагрузки
$optimalParams = @{
    CacheSizeMax = 1024 * 1024 * 1024  # 1GB кэша
    CacheSizeMin = 256 * 1024 * 1024   # 256MB минимальный кэш
    MaxVerPages = 8192                 # Максимум версий страниц
    LogFileSize = 64 * 1024 * 1024     # 64MB лог файлы
    LogBuffers = 8192                  # Буферы логов
    CircularLog = $true                # Круговые логи для производительности
    Recovery = $false                  # Отключить восстановление для временных БД
    EnableIndexChecking = $true        # Проверка индексов
}

# Включение сжатия
[Microsoft.Isam.Esent.Interop.Windows8]::JetSetSystemParameter(
    $instance,
    [JET_SESID]::Nil,
    [JET_param]::EnableCompression,
    1,
    $null
)

Распространённые ошибки и их решение

try {
    # Типичные ошибки и их коды
    $errorCodes = @{
        0xFFFFFFFF = "JET_errSuccess"
        0x80004005 = "JET_errInvalidParameter"
        0x80004002 = "JET_errOutOfMemory"
        0x80004003 = "JET_errFileNotFound"
        0x80004004 = "JET_errDiskFull"
        0x80004006 = "JET_errWriteConflict"
    }

    # Обработка ошибок транзакций
    [Api]::JetBeginTransaction($session)
    # ... операции
    [Api]::JetCommitTransaction($session, [CommitTransactionGrbit]::LazyFlush)
}
catch [Microsoft.Isam.Esent.Interop.EsentErrorException] {
    Write-Warning "Ошибка ESE: $($_.Exception.ErrorCode.ToString('X'))"

    # Откат при ошибке
    if ($session -ne $null) {
        [Api]::JetRollback($session, [RollbackTransactionGrbit]::None)
    }

    # Проверка места на диске
    if ($_.Exception.ErrorCode -eq 0x80004004) {
        Write-Error "Недостаточно места на диске"
    }
}
finally {
    # Обязательная очистка
    if ($tableid -ne [JET_TABLEID]::Nil) {
        [Api]::JetCloseTable($session, $tableid)
    }
}

Рекомендации по использованию

Когда использовать ESE:

✅ Используйте ESE если:

• Требуется максимальная производительность в Windows
• Работа с Active Directory или Exchange данными
• Высокочастотные операции вставки (логгирование, телеметрия)
• Встроенное решение без зависимостей

❌ Не используйте ESE если:

• Нужна кроссплатформенность
• Требуется простой высокоуровневый API
• Работа в PowerShell Core на Linux/macOS
• Маленький проект с простыми запросами

Альтернативы для PowerShell 7.5:

1. SQLite с драйвером Microsoft.Data.Sqlite — для кроссплатформенности
2. LiteDB — NoSQL .NET база данных
3. RocksDB через P/Invoke — максимальная производительность

Практический совет:

Для PowerShell 7.5 в Windows рекомендую использовать обёртку:

# Создать обёрточный модуль для ESE
function Invoke-Esent {
    param(
        [Parameter(Mandatory)]
        [ScriptBlock]$ScriptBlock
    )

    # Запуск в Windows PowerShell сессии
    $session = New-PSSession -UseWindowsPowerShell

    try {
        Invoke-Command -Session $session -ScriptBlock {
            param($block)
            Add-Type -AssemblyName "Microsoft.Isam.Esent.Interop"
            & $block
        } -ArgumentList $ScriptBlock
    }
    finally {
        Remove-PSSession $session
    }
}

# Использование
Invoke-Esent -ScriptBlock {
    $instance = New-Object Microsoft.Isam.Esent.Interop.Instance("Temp")
    # ... операции с ESE
}

Заключение

ESE — это мощный инструмент для высокопроизводительных Windows-приложений, но использование из PowerShell 7.5 требует обходных путей. Для большинства задач PowerShell лучше подходят SQLite или другие кроссплатформенные решения, но если вам нужна максимальная производительность в чистой Windows-среде и вы готовы к сложностям низкоуровневого API — ESE может быть отличным выбором.

Критически важно: Всегда используйте try/finally блоки для освобождения ресурсов ESE, так как они не управляются сборщиком мусора .NET!