Мультиплатформенний AOT з SQLite: Як зробити його функціональним
Введение
Нативний AOT обіцяє перетворити ваші .NET-приложения на крихітні , саморобні МSK2 згортаючі executables, які починаються миттєво і запускаються будь-де DllNotFoundException крахи, боролися з переходними зависимостямиM SK1 і цікавилися, чому PublishSingleFile=true не об 'єднує все в один файл. МСК1 Це Kompletний інструктор для początkujących, МСК3 до МСК4, який допоможе вам зрозуміти, як працювати з SQLite на Native AOT. МSK5 - будувати для багатьох платформ, МSK6 - автоматизувати релізи за допомогою GitHub Actions. . - до кінця, , - у вас будуть двойники МСК10 - МБ, які працюють на Windows. МКС11 - Linux. МСС12 - Raspberry Pi, МКС13 - macOS. МУС14 - з нульовими віддаленнями.
Що таке АОТМСК0 МSK1 І чому вам варто хвилюватисяМКС2
Дозвольте почати з абсолютних базових даних. Якщо ви коли-небудь створили МSK2NET-програму і зацікавились, чому вам потрібно заinstalувати M SK4NET Runtime" на серверах або чому ваші консольні додатки займають секунду, щоб розпочати його перший раз , AOT є відповіддю на ці проблеми
Як .NET нормально працює (JIT Compilation)
Коли ви пишете код C# і створюєте вашу програму , компілятор не виробляє коду для машини, який ваш ЦП може безпосередньо виконати МSK3 Натомість Середній мова (ILM SK1— подумайте про це як про половину шляху між вашим кодом C # і справжніми інструкціями машини
Коли ви запускаєте свою .NET app, ось тутM SK2 що трапляється :
- Ваш комп 'ютер завантажує програму .NET Runtime (особливу програмуM SK2
- Час запуску читає ваш код IL
- ПростоМСК0ВМSK1Time (JITM SK3 компілятор перетворює IL в нативний код машини під час запуску вашої програми
- Врешті-решт, ваш процесор виконує код машини
Це як мати перекладача, який читає ваш рецепт (ILM SK1 і вербально перекладає його на шеф-кухаря.
- .NET Czas запуску 50-150MB додаткових файлів, які вам потрібно застосувати
- Компілятор JIT витрачає час на переклад коду ( чому ваша програма повільна впершеM SK1
- Сам компілятор JIT сидить в пам 'яті, поки ваша програма працює
Введіть AOT (НапередМSK1 ІзM SK2Time Compilation)
Нативний AOT перевертає цю модель на голову. Замість того, щоб перекладати ваш код в час запуску, він перекладає все вчасно. В результаті ви отримуєте єдиний доступний файл, який містить справжній код машини, який ваш процессор може працювати безпосередньо — без часу запуску МSK2 без перекладача
Подумайте про це, як отримати професійно перекладений рецепт замість того, щоб найняти живого перекладача.
Різниця в перевагах гри
Ось що дасть вам місцевий тест
1. Невеликі executablesМSK0 10-30MB замість МSK2MBM SK3
Ваша програма і все, що їй потрібно, з 'являється в одному маленькому двоичному файлі. Немає окремих файлів на час запуску.
2. миттєвий запуск: МSK1 швидший холодний старт
Мої тести: звичайні M SK1 NET знадобився ~800 ms для запуску, AOT знадобався МSK4msMSC5 Там МSK6 не є JIT теплею
3. Нульові залежності: Ні
Ви можете скопіювати вашу програму на будь-яку машину з правильною системною системою. (WindowsM SK1Linux/Mac) і вона просто працює.
4. Менше використання пам 'яті: про МSK1 меншу пам 'ять
Ніяких компіляторів JIT, які сидять в пам 'яті. В моїй Ґейтевейній програмі
5. Краще для обмежених умов: Praces where JIT canM SK1t
Деякі середовища (одні контейнери Докера МSK1 iOS МSK2 вбудовані системи ) не дозволяють генерувати код на час запуску \ . AOT працює повсюди .
Торгівля - оффс МSK1 там МSK2 завжди ловить )
AOT - це МСК0 , а не магія, ".", Ви МСК2 , flexibilність торгового циклу для оптимізації з самого початку .
1. Немає генерації динамічного коду
Будь-що, що генерує код в часі запуску,
System.Reflection.Emit( динамічно створювати типиM SK1- Завантаження динамічної збірки (завантаження DLL в часі запускуM SK1
- Найкращі трюки відображання
Більшість нормальних кодів .NET є непоганими ,, але деякі фреймворки, які сильно залежать від відображання, потребують спеціальної конфігурації
2. Платформа
компіляція JIT виробляє IL, що працює на будь-якій платформі. AOT виробляє одна конкретна платформа. Потрібно будувати окремо для
- Windows x64
- Linux x64
- Linux ARM64 M SK1Raspberry Pi)
- macOS Intel
- macOS Apple Silicon
Ми ' обробимо автоматизацію цього пізніше за допомогою GitHub Actions .
3. Довгий час будування
Замість комп 'ютерного комп' ютера в секунду, AOT комп' єлює весь шлях до коду машини . Очікувати M SK2 хвилини замість МSK3 секунд МSK4 Це
4. Деякі функції потребують додаткової конфігурації
Серіалізація JSON, Cadre Entity, і будь-що, що використовує важке відображання, може потребувати explicitly сказати компілятору, які типи зберігати
Коли використовувати AOT?
Нативний AOT ідеальний для:
- інструменти CLI: КомандаM SK1ланцюжні інструменти, які мають значення для миттєвого запуску
- Мікросервіси: Менькі зображення докера , швидше масштабування в Kubernetes
- Без сервера/Lambda: Холодний час запуску безпосередньо впливає на ваш рахунок
- Пристрої на краю: Raspberry Pi, IoT-пристрої з обмеженими ресурсами
- Застосунки портів: Реверсивні прокси МSK1 API-вороти з високою пропускною спроможністю
- Програмні інструменти: Зарядити один МSK1exe без МSK2установити .NET перший \ " крок
Перейдете до AOT для:
- Традиційні веб-приложения, де час запуску не має значення
- Apps, які використовують важкі рамки Entity з багатьма міграціями
- Системи плагинів, які завантажують DLL динамічно
- Щось, що генерує код в часі запуску
Для інструментів CLI: МСК0, мікросервіси, МСК1, контейнери, МSK2 та рёберні пристрої. МSK3. покращення - це гра, МСК4, зміна, MСК5. Але є й помилка: МСк6, коли ви додаєте бази даних, М Ск7, а саме SQLite
Проблема SQLite
Тепер, коли ви розумієте, що таке AOT, дайте нам поговорити про один із найбільших болюшних моментів: :, SQLite, .. Це стіна, яку вдарили більшість людей, коли намагалися використовувати AOT за допомогою бази даних
Що трапляється? ( Перечаровуючий досвід
Ось типова подорож:
- Ви додаєте
Microsoft.Data.Sqliteдо вашого проекту - Ви налагоджуєте
PublishAot=trueу вашому.csproj - Збудування завершено без помилок—все виглядає добреM SK1
- Ви запустите програму і відразу отримаєте:
DllNotFoundException: Unable to load DLL 'e_sqlite3' or one of its dependencies
Ваша програма скасується перед тим, як вона зможе щось зробити.. Що дає?
Усвідомлення місцевих бібліотек (Quick DetourM SK1
Щоб зрозуміти проблему, вам потрібно знати про місцевих бібліотек.
SQLite не має коду 't, написанного в .NET—itMSC3, написаного у CM SK4, а також в комп 'ютері, написанному на платформі
e_sqlite3.dllна Windowslibe_sqlite3.soна Linuxlibe_sqlite3.dylibна macOS
Коли ви використовуєте Microsoft.Data.Sqlite у звичайному .NETM SK1 це' це просто обгортання навколо цієї рідної SQLite-ліберарії . В часи запускуMSC4 він намагається динамічно навантаження відповідний нативний файл для вашої платформи.
Це працює добре з звичайним .NET, тому що
- Час запуску може завантажувати бібліотеки динамічно
- Пакети NuGet можуть включати в себе нативні бібліотеки для всіх платформ
- Справа відбирається під час запуску
Чому AOT зупиняє це
Нативний AOT має дві характеристики, які суперечать підходу SQLite'
1. Agгресивне витинання: AOT видаляє будь-який код, який він думає, що ви не використовуєтеM SK1 . Якщо він не зможе' статично довести, що вам чогось потрібноMSC4 він буде видаленийМSK5 Завантаження динамічної бібліотеки заплутає триммераMska6 він не можеMска7 не побачить зв 'язку між вашим кодом та нативним SQLite DLL
2. Без динамічної підтримки завантаження: AOT виробляє самовідтворюваний binар, що складається з - і заміщується в . Він сподівається, що всі нативні віддалежності будуть явно пов 'язані у часі компілі`ра МSK3 не загружаються динамічно в часі запуску
Результат: Microsoft.Data.Sqlite сподівається знайти нативну библиотеку SQLite в час запуску,, але AOT або її відрізала, або не знає, як її правильно об 'єднати
Таємниця переходної залежності
Ще гірше, якщо у вас є інші пакети NuGet, які використовують SQLite (, як деякі бібліотеки ORM або мій mostlylucid.ephemeral.complete пакет), ви можете отримати багато неповносправних провайдерів SQLite у вашому дереві залежності.
Кожен постачальник намагається працювати по-іншому:
- Можна очікувати, що ОС-наділити SQLite (только WindowsM SK2
- Інший може об 'єднати свій власний SQLite
- Інший може використовувати іншу версію рідної бібліотеки
Компілятор AOT сплутається з тим, який саме комп 'ютер треба використовувати, і часто в результаті він не включає жодного з них.
Рішення: Використовуйте Bundle
Рішення - SQLitePCLRaw.bundle_e_sqlite3—специальний пакет NuGet, розроблений спеціально для роботи з AOT
Dodaj ці два пакети до проекту:
<ItemGroup>
<PackageReference Include="Microsoft.Data.Sqlite" Version="9.0.0" />
<PackageReference Include="SQLitePCLRaw.bundle_e_sqlite3" Version="2.1.10" />
</ItemGroup>
Що робить Bundle?
І bundle_e_sqlite3 пакет відрізняється від звичайних поставщиків SQLite:
1. Це включає в себе до-с Comppiled нативні SQLite библиотеки для кожної головної платформиM SK2
- Windows (xM SK1 x 86, ARM64)
- Linux (x64, ARM64, muslM SK3засаджені distros, такі як AlpineMSC4
- macOS (x 64 Intel, ARMM SK3 Apple SiliconMSC4
2. Ці нативні бібліотеки упаковані так, як компілятор AOT розуміє
Бюндл чітко визначає свої рідні залежності, так що компілятор AOT знає, як включити їх у кінцевий бінар.. Без динамічного завантаження.
3. ItM SK1s розроблені для інтерфейсних будівок platform
Один пакет працює на всіх платформах. Ви не маєте ' не потребуєте платформи МSK2 конкретні пакети чи кондиціональні відмітки M SK3
Чому це працює?
Пам 'ятайте дві проблеми, які ми визначили
Проблема 1: AOT's trimming removes libraries it can 't see being used
- Рішення: Бюндл експлицитно декларує свої рідні бібліотеки як будові активи, які повинні бути включені
Проблема 2: AOT не поддерживает ' не підходить динамічному завантаження
- Рішення: Бюндл статтично поєднує бібліотеки SQLite в час компіліляції
Результатом:, коли ви будуєте для Windows xM SK1 пакет включає e_sqlite3.dll. Коли ви будуєте для Linux ARM libe_sqlite3.so. Все просто працює
Критичний: Почати Bundle (DonM SK2 не перемикати цього !)
Ось ця частина, яка піднімається: 90% людей, які пробують використовувати SQLite з AOT ,, включно зі мною на моїй першій спробі
З нормальним .NET, пакет SQLite автоматично запускає себе вперше, коли ви використовуєте SQLite . Магія відбувається за кулисами
З місцевим AOT, ця автоматична інisiaлізація не працює ' не працює мусить запускати вручну пакет на самому початку вашої програми.
Ось вам потрібна магічна лінія.
using SQLitePCL;
public class Program
{
public static void Main(string[] args)
{
// THIS IS CRITICAL: Initialize SQLite FIRST, before ANYTHING else
SQLitePCL.Batteries.Init();
// Now you can do normal application setup
var builder = WebApplication.CreateBuilder(args);
// This is now safe - SQLite is initialized
builder.Services.AddDbContext<MyDbContext>(options =>
options.UseSqlite("Data Source=app.db"));
var app = builder.Build();
app.Run();
}
}
Що робить Batteries.Init() Do?
Цей метод вказує на пакет SQLite до:
- Найти правильну нативну библиотеку SQLite для вашої теперішньої платформи
- Загрузити його в пам 'ять
- Встановіть всі зв 'язки між
Microsoft.Data.Sqliteі місцеву бібліотеку
Це "'" називається "" МSK1 "" "" батареї "" , МSK2 "", тому що це "" мск3 "" і "" mск4 "" бактерії включені в комплект "".
Де його розмістити
Помістити Batteries.Init() як у першому рядку у вашому Main метод, передM SK1
- Створювання កម្មវិធី-будівника
- Konfiguracja ін 'єкції залежності
- Відкриваємо будь-які зв 'язки з базою даних
- Читання файлів конфігурації, які можуть використовувати SQLite
Подумайте про це, як про підключення до пристрою перед тим, як його ввімкнути. Якщо ви спробуєте використовувати SQLite перед телефоном Init()МSK0 ви ' все ще отримаєте DllNotFoundException навіть якщо DLL правильно побудований в вашій програмі.
Що станеться, якщо ви забудете
Якщо ви забули подзвонити Batteries.Init(), ваша програма буде
- Збудувати успішно (комплікатор виграв ' не попереджає вас МSK2
- Почати роботу
- Скасується момент, коли він намагається використовувати SQLite з:
DllNotFoundException: Unable to load DLL 'e_sqlite3' or one of its dependencies
Це бентежить, тому що DLL є з 'єднані в вашу програму—it's just not initializedM SK2
Завершити конфігурацію проекту
Ось цілковита .csproj сконфигурований для мультиплатформи Native AOT з SQLite:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<!-- Native AOT -->
<PublishAot>true</PublishAot>
<PublishTrimmed>true</PublishTrimmed>
<TrimMode>full</TrimMode>
<InvariantGlobalization>true</InvariantGlobalization>
<!-- Single File -->
<PublishSingleFile>true</PublishSingleFile>
<StripSymbols>true</StripSymbols>
<!-- Optimization -->
<OptimizationPreference>Speed</OptimizationPreference>
<!-- Multi-platform targets -->
<RuntimeIdentifiers>
win-x64;win-arm64;linux-x64;linux-arm64;osx-x64;osx-arm64
</RuntimeIdentifiers>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Data.Sqlite" Version="9.0.0" />
<PackageReference Include="SQLitePCLRaw.bundle_e_sqlite3" Version="2.1.10" />
</ItemGroup>
</Project>
Пояснення ключових ustawień (По-іншому англійськійM SK1
Дозвольте мені розібратися, що робить кожен із цих настроїв:
PublishAot=true
Це головний перемикач, який дозволяє комп 'ютеризувати нативні AOT. Без цього , ви отримуєте нормальний МSK2 поведінку NET M SK3 комп' ютеризацію JIT ). З цим MSC5 ви рухаєтесь вперед MST6 з МST7 час комп ’ ютеризованого нативного кодуMST8
PublishTrimmed=true і TrimMode=full
Вони кажуть компілятору видалити будь-який код, який ви не використовуєте.
PublishTrimmed=trueдозволяє збільшуватиTrimMode=fullозначає " бути агресивним , позбутись усього, що можна
Остереження: Це може зламати код, який використовує важке відображання ( так само як деякі серіалізатори JSON або ORMs МSK2 тому що триммер не завжди бачить те, чим ви користуєтесь через відображение
InvariantGlobalization=true
Це видаляє всі дані про культуру-конкретні дані з вашої додатки
Тільки встановіть це до true якщо ваша програма:
- Тільки англійська
- Чи не потрібне'культураМSK1конкретна датаM SK2час форматування
- Використовується тільки звичайний (байтМSK1замістьM SK2байта) порівняння струн
Якщо ви' створюєте інструмент CLI або API, який не заважає локалізації ', то це безкоштовний заощаджень. МSK3. Якщо ви (МSK4) створюєте дещо, що потребує форматування дат для французьких користувачів чи правильного сортування турецких текстів, то пропустите це налаштування.
PublishSingleFile=true
Об 'єднує все в один функціональний файл. Замість того, щоб мати
myapp.exe
myapp.dll
System.Text.Json.dll
... 50 more files
Ви отримуєте лише:
myapp.exe
Це набагато легше застосувати.
StripSymbols=true
Символи розладів допомагають розладникам показати вам змінні імена та числа лінії при розладах. ВониM SK1потрібні під час розробки, але додайте кілька мегабайт до вашого кінцевого бінарного.
Дане налаштування видаляє їх.. Ваша програма працює точно так само.
OptimizationPreference=Speed
Це вказує компілятору на те, що prioritувати при прийняття рішень:
Speed: Робіть це швидко (трішки більші бінарі МSK2 але краще продуктивність МSK3Size: Зробіть його маленьким (трішки повільнішим МSK2 але мінімальний бінарний розмір
Для більшості застосувань, Speed є правильним вибором. Різниця розміру зазвичай лише 2-3MBM SK2 але різниця в wydajності може бути помітна
RuntimeIdentifiers
Це визначає, які платформи ви хочете підтримувати.
Доступні идентификатори:
win-x64МSK0 Windows 64-bit (IntelM SK3AMD)win-arm64: Windows ARM64 (Surface Pro XM SK3 і т.д.linux-x64: Linux 64-bit МSK2Ubuntu, DebianMSC4 RHELM SK5 і т.д.linux-arm64: Linux ARMM SK1 (Raspberry Pi МSK3 AWS Graviton)osx-x64: macOS Intelosx-arm64: macOS Apple Silicon
Ви будуєте одну платформу за раз, використовуючи dotnet publish -r linux-x64, наприклад
Збудова для декількох платформ
Пам 'ятаєте, як я казав, що AOT вимагає платформи-спеціалізованих конструкцій? Потрібно комп' ютерити окремо для WindowsM SK2 Linux x 64, Linux ARMМSK4 macOS IntelMska5 і macOS Apple SiliconMSC6 Роблячи це ручно було б нудним МSK7 але ми можемо зробити це автоматизованоMسک8
Що таке GitHub Actions?
Якщо ви не знаєте, що це таке:
Подумайте про це, як having a build server that:
- Спостерігає за вашим repository GitHub
- Коли ви натискаєте таку позначку,
v1.0.0 - Він автоматично запускає Windows, Linux, та віртуальні машини macOS
- Збудовує вашу програму для всіх платформ паралельно
- Створює реліз GitHub з усіма прикріпленими бінарами
Все це працює на GitHub, на серверах ', МSK1, ви не маєте потреби підтримувати будь-яку інфраструктуру
Полний робочий процес побудови
Тут' це робочий процес GitHub Actions, який будується для всіх основних платформ автоматично:
name: Build Native AOT Binaries
on:
push:
tags:
- 'v*'
jobs:
build-binaries:
name: Build ${{ matrix.runtime }}
runs-on: ${{ matrix.os }}
strategy:
matrix:
include:
- os: ubuntu-latest
runtime: linux-x64
artifact-name: myapp-linux-x64
- os: ubuntu-latest
runtime: linux-arm64
artifact-name: myapp-linux-arm64
- os: windows-latest
runtime: win-x64
artifact-name: myapp-win-x64
- os: macos-latest
runtime: osx-x64
artifact-name: myapp-osx-x64
- os: macos-latest
runtime: osx-arm64
artifact-name: myapp-osx-arm64
steps:
- uses: actions/checkout@v4
- name: Setup .NET
uses: actions/setup-dotnet@v4
with:
dotnet-version: '9.0.x'
- name: Install ARM64 tools (Linux ARM64 only)
if: matrix.runtime == 'linux-arm64'
run: |
sudo apt-get update
sudo apt-get install -y clang zlib1g-dev gcc-aarch64-linux-gnu
- name: Publish
shell: bash
run: |
# Set objcopy for ARM64 cross-compilation
if [ "${{ matrix.runtime }}" = "linux-arm64" ]; then
OBJCOPY_PARAM="-p:ObjCopyName=aarch64-linux-gnu-objcopy"
else
OBJCOPY_PARAM=""
fi
dotnet publish \
-c Release \
-r ${{ matrix.runtime }} \
--self-contained \
--output ./publish/${{ matrix.runtime }} \
-p:PublishAot=true \
-p:PublishTrimmed=true \
-p:StripSymbols=true \
$OBJCOPY_PARAM
- name: Create distribution package
shell: bash
run: |
mkdir -p ./dist
cd ./publish/${{ matrix.runtime }}
# Copy the main executable
cp myapp${{ matrix.file-ext }} ../../dist/
# CRITICAL: Copy native libraries (SQLite and any other native dependencies)
# PublishSingleFile bundles .NET code, but native DLLs remain separate
cp *.dll ../../dist/ 2>/dev/null || true
cp *.so ../../dist/ 2>/dev/null || true
cp *.dylib ../../dist/ 2>/dev/null || true
# Copy config files if needed
cp ../../appsettings.json ../../dist/ || true
cd ../../dist
# Create archive with all files
if [ "${{ runner.os }}" = "Windows" ]; then
7z a -tzip ../${{ matrix.artifact-name }}.zip *
else
tar czf ../${{ matrix.artifact-name }}.tar.gz *
fi
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: ${{ matrix.artifact-name }}
path: |
${{ matrix.artifact-name }}.zip
${{ matrix.artifact-name }}.tar.gz
retention-days: 7
if-no-files-found: ignore
Як працює цей робочий процес
Якщо YAML виглядає залякаючим, то це те, що він робить простою англійською.
1. Триггер МSK1on: push: tags)
Рабочий процес закінчується, коли ви натискаєте на значок Git, що починається з v ( як v1.0.0, v2.3.1). Це стандартний спосіб позначити версії, які випущені
2. Матриця
Це розумна частина. Замість того, щоб писати п 'ять різних потоків роботи, ми визначаємо матрица з конструкцій:
- Кожна будівля отримує іншу
os(штурмовий станокM SK1 іruntime(целева платформаM SK1 - GitHub Actions запускає всі п 'ять збудувань паралельно
- Кожна з них створює артефакт (с Comppiled binary)
Отже, коли ви натискаєте v1.0.0, GitHub одночасно:
- Розпочинає машину Ubuntu для створення Linux x64 та ARMM SK1
- Викручує комп 'ютер Windows для створення Windows x64
- Викручує машину для створення macOS x64 та ARMM SK1
3. Поступи в кожній будівлі
Кожна платформа робить ті самі кроки:
- Код замовлення: Збирає вихідний код з репозитори
- Установка .NET: Встановлює SDK
- Установити інструменти ARM64 (Linux ARM64 тільки ): Встановлює інструменти компіляції
- Публикація: Перебіги
dotnet publishз флагами AOT для цієї конкретної платформи - завантажити артефакт: Заpisує згенерований бінар, щоб наступна робота могла отримати доступ до нього
4. Результат
Після того, як всі будинки завершені, у вас є п 'ять артефактів M SK1 бінарів ) готових до розповсюдування. Ви можете завантажити їх з запуску Действия МSK4 або використати другу роботу для створення автоматичної релізу GitHub МSK5 не показана в цьому фрагменті МСК6 але легко додавати М СК7
Критичний: Нативні бібліотеки не об 'єднані
Ось що мене годинами збентежило. PublishSingleFile=true лише пакети .NET коду. Нативні бібліотеки, такі як SQLite's e_sqlite3.dll залишатися окремо.
Ось чому такий важливий крок "Створити дистрибутивні пакети "
# Copy native libraries - these are NOT included in the main executable
cp *.dll ../../dist/ 2>/dev/null || true # Windows
cp *.so ../../dist/ 2>/dev/null || true # Linux
cp *.dylib ../../dist/ 2>/dev/null || true # macOS
І 2>/dev/null || true частина означає " якщо немає файлів, які б співпадали з цією моделью , не роби МSK2 не зазнаєш невдачі M SK3 просто продовжуй ." Це дозволяє одному скрипту працювати на всіх платформах
Що ви розподіляєте:
- Windows:
myapp.exe+e_sqlite3.dll( з 'єднані разом у ZIPM SK1 - Linux:
myapp+libe_sqlite3.so( з 'єднані разом у смолину - macOS:
myapp+libe_sqlite3.dylib( з 'єднані разом у смолину
Пользовачі витягують архів і запускають програму executable. Нативна bibliotekа SQLite сидить поруч з нею, а пакет знаходить її автоматично під час запуску.
Чому ручна триггерація корисна
Зверніть увагу на workflow_dispatch триггер вгорі:
on:
push:
tags:
- 'v*'
workflow_dispatch:
inputs:
version:
description: 'Version to publish'
required: true
Це дозволяє відштовхувати будування вручну з веб-интерфейсу GitHub', не натискаючи на тегM SK1 корисний для тестування робочого процесу або створення бета-будів.
ARM64 КроссМSK1Коміляція
Збудувати Linux ARM requires special attention. You need cross-compilation tools and must specify the correct objcopy інструмент:
# Install tools
sudo apt-get install gcc-aarch64-linux-gnu binutils-aarch64-linux-gnu
# Build with objcopy specified
dotnet publish \
-r linux-arm64 \
-p:PublishAot=true \
-p:ObjCopyName=aarch64-linux-gnu-objcopy
Без ObjCopyName параметр, лінгер не працює з криптичними помилками щодо невідомих форматів файлівM SK1
Результати світу
Ось що я досягла з моєю робототехнікою YARP-посередньою платформою для розпізнавання роботів з середнім програмним забезпеченням і логінгом SQLite. Це справжній проект, який ви можете завантажити з GitHub.
Бінарні розміри (Из реальных випусків GitHub)
Це справжні розміри файлів з моїх випусків на GitHub, не теоретичні підрахункиM SK1
| Платформа МSK1 Виконовні МSK2 SQLite Native DLL | Общий розмір архіву M | ||||
|---|---|---|---|---|---|
| Windows x 10.9MB МSK0ZIP) M SK2 | |||||
| Linux xM SK1 | 10.8 | МSK4 | 12.4MB МSK0тар.gzM SK2 | ||
| Linux ARMM SK1 | 9.9 | МSK4 | 11.4MB МSK0тар.gzM SK2 | ||
| macOS Intel 13.0MB МSK0тар.gzM SK2 | |||||
| macOS ARMM SK1 | МSK3 | 11.5MB МSK0тар.gzM SK2 |
Порівняйте це з самовисадками -, що містять .NET МSK2 в 130-150MB на одну платформуМSK0 Ми ' говоримо про 10-12x зменшення розміру.
Розрив:
- Головний інтерактивний код : Ваш комп 'ютерний код
- Нативний DLL: Машина баз даних SQLite (записана в CM SK2
Обидві файли мають бути розподілені разом. , але вони ' досі значно менші, ніж традиційні.
Стартування
Холодний старт (перша запити відправлена ) на скромній Linux VPS МSK2
- Само собою-вміщується M SK1NETМSK0 ~800м
- Нативний АОТМSK0 ~150м
- ПоліпшенняМSK0 81% швидше
Це надзвичайно важливо для
- Без сервера/ Функції Lambda МSK1 Ви платите за милісекундуM SK2
- Контейнери, які часто збільшують чи зменшують
- Програмні інструменти CLI, де кожен виклик починається з чистого
Використовування пам 'яті
Неактивна пам ’ ять ( запуск коридору , без руху МSK2
- Само собою-вміщується M SK1NETМSK0 85MB
- Нативний АОТМSK0 42MB
- ПоліпшенняМSK0 51% скорочення
Під навантаженням (1000 запитиM SK1секундиМSK2
- Само собою-вміщується M SK1NETМSK0 ~320MB
- Нативний АОТМSK0 ~180MB
- ПоліпшенняМSK0 44% скорочення
Менша пам 'ять означає:
- Більше контейнерів на одного хоста
- дешеві рахунки на хостинг хмар
- Можливість використання ресурсів-ушкоджені пристрої M SK1Raspberry Pi, IoTMSC3
Зазвичайні водоспади
1. Забуття Batteries.Init()
Це і є помилкою #1 SQLitePCL.Batteries.Init() на самому початку вашого Main метод спричиняє розбіжності в часі запуску.
Установка:
public static void Main(string[] args)
{
SQLitePCL.Batteries.Init(); // FIRST LINE
// ... rest of your code
}
2. Не розповсюджуючи місцевих бібліотек
Це помилка #2, і я отримав двічі МSK1 PublishSingleFile=true не об 'єднує рідних SQLite DLL у ваші функціональні. Ви повинні розповсюджувати їх разом з вашими функціональними.
Що станеться, якщо ви забудете:
- Ваша програма добре працює
- Він працює добре на вашому dev-аналізаторі ( де SQLite може вже бути zainstalowanий )
- Він руйнується на етапі виробництва
DllNotFoundException
Установка:
Під час пакування вашого випуску завжди вміщувати
myapp.exe # Your main executable
e_sqlite3.dll # SQLite native library (Windows)
# or libe_sqlite3.so # SQLite native library (Linux)
# or libe_sqlite3.dylib # SQLite native library (macOS)
У ваших програмах GitHub або сценаріїв розгортання:
# Copy ALL native libraries from the publish directory
cp *.dll ./dist/ 2>/dev/null || true
cp *.so ./dist/ 2>/dev/null || true
cp *.dylib ./dist/ 2>/dev/null || true
Пользователю треба витягти архів і запустити програму, яку можна виконати. Нативна бібліотека повинна знаходитись в тому ж каталогі
3. Використовування winsqlite3 Поставщик
Ви можете побачити рекомендації для використання SQLitePCLRaw.provider.winsqlite3 на Windows, щоб використовувати ОС-подарований SQLite. DonM SK2t . Він працює лише на WindowsMSC4 вимагає ручної інициалізаціїMST5 та розривів міжMСК6платформенними будівлямиМСК7 Тримайся з bundle_e_sqlite3.
4. Тримні попередження з ядром EF
Якщо ви' користуєтесь ядром фреймворка Entity Framework з SQLite(SQLite) (Entity Framework Core), то, отримаєте(M SK2) попередження про зрізання( trim warnings ) (ILM SK4 IL3050). Зазвичай, вони безпечні для подавлення для EF Core(EF Core)(Entity Framework Core) '(S SQLite Provider)(SQLite provider),, але перевіряйте їх досконало( test thoroughly)
<PropertyGroup>
<NoWarn>$(NoWarn);IL2026;IL3050</NoWarn>
</PropertyGroup>
Ще краще, подумайте про використання Даппера чи сирого ADO.NET з SQLite для AOT-пристосуваньM SK2 вони ' є більш АOTМSK4 дружні МSK5
5. Позбавлені інструментів для візуального студійного проектування
На Windows, Native AOT вимагає Visual Studio's MSVC linkerM SK2 Якщо ви будуєте за межами Developer Command PromptMSC3 ви ' отримаєте помилки про vswhere.exe. GitHub Actions обробляє це автоматично, але для локальних конструкційM SK2 використовуватиMSC3
- Командний пробір програмістів для VS 2022
- Програміст PowerShell для VS 2022
Або inicialізувати середовище у вашому скрипті будування:
& "C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\Launch-VsDevShell.ps1" -Arch amd64
dotnet publish -c Release -r win-x64
Коли використовувати місцевий AOT
Нативний AOT ідеальний для:
- інструменти CLI: Негайний запуск
- Мікросервиси та контейнери: Менькі зображення , швидше масштабування
- Пристрої на краю: Raspberry Pi, IoT-пристрої з обмеженими ресурсами
- Без сервера/Lambda: Критичний час старту
- Gateway/ прокси-приложения: високий пропускна спроможність , низький об 'єм
Уникніть AOT для:
- Коральне використання Framework Heavy Entity (багато міграції, складні питанняM SK2
- Reflection-важкі застосування
- Динамічні системи плагинів
- Застосунки, які потребують генерації коду в часі запуску
Список перевірок швидкого старту
Якщо ви' прочитали цілий пост і просто хочете, щоб список перевірок йшов за вами , - ось вам(M SK2)
1. Dodaj пакети
<PackageReference Include="Microsoft.Data.Sqlite" Version="9.0.0" />
<PackageReference Include="SQLitePCLRaw.bundle_e_sqlite3" Version="2.1.10" />
2. Konfigurуйте ваш .csproj для AOT:
<PublishAot>true</PublishAot>
<PublishTrimmed>true</PublishTrimmed>
<TrimMode>full</TrimMode>
<InvariantGlobalization>true</InvariantGlobalization>
<PublishSingleFile>true</PublishSingleFile>
<StripSymbols>true</StripSymbols>
<OptimizationPreference>Speed</OptimizationPreference>
3. Ввімкніть SQLite на початку вашого Main метод:
SQLitePCL.Batteries.Init();
4. Збудувати для вашої цільової платформи
dotnet publish -c Release -r linux-x64 --self-contained
5. Випробуйте ваш бінарний — він повинен просто працювати без залежностей !
Завершення
Знання SQLite, що працює з нативним AOT, не є очевидним, але як тільки ви знаєте магічне вcantation,SQLitePCLRaw.bundle_e_sqlite3 + Batteries.Init()—it 's straightforward. Прибутки суттєвіM SK3 крихітні бінарні бітальніM Sk4 миттєвий запускM sk5 і можливість застосувати на будь-якій платформі без залежності від часового графікуM Ск6
Для будь-кого, який створює інструменти CLI. , ворота , або пристрої з МSK2 NET | , Нативний AOT з SQLite тепер є реальним варіантом. \ . Тут представлений робочий процес GitHub Actions автоматизує весь процес створення мультиплатформ.
Якщо ви' - нова(а) людина(а), яка працює на AOT(AOT1), - починайте маленьку програму(МSK2). Спочатку конвертуйте простий CLI інструмент або утилит(а). МSK3 - знаходитесь у зручному місці в процесі будування. МSK4 - дізнайтеся, чого очікувати. , - розумієте обмеження.
Екосистема .NET стає все більш дружньою з точки зору AOTM SK1приємною . Більшість сучасних бібліотек або працюють беззаперечно, або мають чітку документацію про підтримку AOT
Реальний досвід розгортання
Я розміщую свій AOT на комп 'ютерні ворота до
- Цифровий океан (Linux x64) - запускається як систематична служба
- Raspberry Pi 5 (Linux ARM64) - розгортання країв для тестування
- Сервер Windows (Windows xM SK1 - працює як Windows Service
- Докерні контейнери Різні варіанти x64 та ARMM SK2
Процес запуску є однаковим всюди:
- завантажити архів з GitHub Releases
- Візьміть його
- Запустити програму, яку можна виконати
Ні "установити .NET Czas запуску МSK2 крок МSK3 Без беззалежності пеклі M. Без конфліктів версії МСК5 Просто витягти і запустити МКК6
Для Docker, мій Dockerfile дуже простий.
FROM debian:bookworm-slim
# Copy just the two files we need
COPY minigw /app/minigw
COPY libe_sqlite3.so /app/libe_sqlite3.so
WORKDIR /app
RUN chmod +x minigw
EXPOSE 5000
ENTRYPOINT ["./minigw"]
Результатом є ~130MB (в основному базовий образ Debiana ). Традиційний МSK2NET контейнер був би МSK3MBM SK4
Повний робочий приклад
Все, що я показав тут - це справжній продукт.
- Подивіться на вихідний код: Найяскравіший.Detection Bot.Console
- Подивіться на робочий процес GitHub Actions: konsol-gatewayM SK1release.yml
- Скачайте попередньо збудовані бінарі: Релізи GitHub
Проект - мінімальний YARP зворотній прокси з середнім програмним забезпеченням для розпізнавання роботів, що записує підписи на SQLite. Демонструє
- Нативний AOT з SQLite
- Платформа Multi- будується за допомогою GitHub Actions
- Об 'єднання рідної бібліотеки
- Розглядання аргументів CLI
- Структуроване вирубування
- Гарний відключення
Клоніруй це , вивчай це, використай це як шаблон для власних AOT-проектів
Ресурс
- Официальна документація .NET Native AOT
- SQLitePCLRaw - хранилище GitHub
- Працюючий приклад: Найяскравіший Bot Detection Gateway
- Моє робоче русло GitHub Actions
Тепер побудуй щось крихітне і швидко.