Místní databáze .NET MAUI

Procházení ukázky

Databázový stroj SQLite umožňuje aplikacím .NET MAUI (Multi-Platform App UI) .NET načítat a ukládat datové objekty ve sdíleném kódu. Pomocí následujícího postupu můžete integrovat SQLite.NET do aplikací .NET MAUI a ukládat a načítat informace v místní databázi:

1. Nainstalujte balíček NuGet.
2. Konfigurujte konstanty.
3. Vytvořte třídu přístupu k databázi.
4. Přístup k datům
5. Pokročilá konfigurace.

Tento článek využívá balíček NuGet sqlite-net-pcl k zajištění přístupu k databázi SQLite a k ukládání položek seznamu úkolů do tabulky. Alternativou je použití balíčku NuGet Microsoft.Data.Sqlite , což je jednoduchý poskytovatel ADO.NET pro SQLite. Microsoft.Data.Sqlite implementuje běžné ADO.NET abstrakce funkcí, jako jsou připojení, příkazy a čtečky dat.

Instalace balíčku NuGet SQLite

Pomocí správce balíčků NuGet vyhledejte balíček sqlite-net-pcl a přidejte nejnovější verzi do projektu aplikace .NET MAUI.

Existuje několik balíčků NuGet s podobnými názvy. Správný balíček má tyto atributy:

• ID: sqlite-net-pcl
• Autoři: SQLite-net
• Owners: praeclarum
• Odkaz na NuGet:sqlite-net-pcl

I přes název balíčku použijte balíček NuGet sqlite-net-pcl v projektech .NET MAUI.

Důležité

SQLite.NET je knihovna třetí strany podporovaná z úložiště praeclarum/sqlite-net.

Konfigurace konstant aplikací

Konfigurační data, jako je název souboru databáze a cesta, se dají v aplikaci uložit jako konstanty. Ukázkový projekt obsahuje soubor Constants.cs , který poskytuje běžná konfigurační data:

public static class Constants
{
    public const string DatabaseFilename = "TodoSQLite.db3";

    public const SQLite.SQLiteOpenFlags Flags =
        // open the database in read/write mode
        SQLite.SQLiteOpenFlags.ReadWrite |
        // create the database if it doesn't exist
        SQLite.SQLiteOpenFlags.Create |
        // enable multi-threaded database access
        SQLite.SQLiteOpenFlags.SharedCache;

    public static string DatabasePath =>
        Path.Combine(FileSystem.AppDataDirectory, DatabaseFilename);
}

V tomto příkladu soubor konstant určuje výchozí hodnoty výčtu SQLiteOpenFlag, které se používají k inicializaci připojení k databázi. Výčet SQLiteOpenFlag podporuje tyto hodnoty:

• Create: The connection will automatically create the database file if it doesn't exist.
• FullMutex: The connection is opened in serialized threading mode.
• NoMutex: Připojení se otevře v režimu více vláken.
• PrivateCache: Připojení se nebude účastnit sdílené mezipaměti, i když je povolené.
• ReadWrite: Připojení může číst a zapisovat data.
• SharedCache: Připojení se bude účastnit sdílené mezipaměti, pokud je povolená.
• ProtectionComplete: Soubor je zašifrovaný a nepřístupný, když je zařízení zamknuté.
• ProtectionCompleteUnlessOpen: Soubor se zašifruje, dokud se neotevře, ale bude přístupný i v případě, že uživatel zařízení zamkne.
• ProtectionCompleteUntilFirstUserAuthentication: Soubor se zašifruje, dokud uživatel zařízení nespustí a odemkne.
• ProtectionNone: Soubor databáze není zašifrovaný.

V závislosti na způsobu použití databáze možná budete muset zadat různé příznaky. Další informace najdete v SQLiteOpenFlagstématu Otevření nového připojení k databázi na sqlite.org.

Vytvoření třídy přístupu k databázi

Třída obálky databáze abstrahuje vrstvu přístupu k datům ze zbytku aplikace. Tato třída centralizuje logiku dotazů a zjednodušuje správu inicializace databáze, což usnadňuje refaktoring nebo rozšíření operací s daty při růstu aplikace. Ukázková aplikace pro tento účel definuje TodoItemDatabase třídu.

Opožděná inicializace

The TodoItemDatabase uses asynchronous lazy initialization to delay initialization of the database until it's first accessed, with a simple Init method that gets called by each method in the class:

public class TodoItemDatabase
{
    SQLiteAsyncConnection database;

    async Task Init()
    {
        if (database is not null)
            return;

        database = new SQLiteAsyncConnection(Constants.DatabasePath, Constants.Flags);
        var result = await database.CreateTableAsync<TodoItem>();
    }
    ...
}

Metody manipulace s daty

Třída TodoItemDatabase obsahuje metody pro čtyři typy manipulace s daty: vytvoření, čtení, úpravy a odstranění. Knihovna SQLite.NET poskytuje jednoduchou relační mapu objektů (ORM), která umožňuje ukládat a načítat objekty bez psaní příkazů SQL.

Následující příklad ukazuje metody manipulace s daty v ukázkové aplikaci:

public class TodoItemDatabase
{
    ...
    public async Task<List<TodoItem>> GetItemsAsync()
    {
        await Init();
        return await database.Table<TodoItem>().ToListAsync();
    }

    public async Task<List<TodoItem>> GetItemsNotDoneAsync()
    {
        await Init();
        return await database.Table<TodoItem>().Where(t => t.Done).ToListAsync();

        // SQL queries are also possible
        //return await Database.QueryAsync<TodoItem>("SELECT * FROM [TodoItem] WHERE [Done] = 0");
    }

    public async Task<TodoItem> GetItemAsync(int id)
    {
        await Init();
        return await database.Table<TodoItem>().Where(i => i.ID == id).FirstOrDefaultAsync();
    }

    public async Task<int> SaveItemAsync(TodoItem item)
    {
        await Init();
        if (item.ID != 0)
            return await database.UpdateAsync(item);
        else
            return await database.InsertAsync(item);
    }

    public async Task<int> DeleteItemAsync(TodoItem item)
    {
        await Init();
        return await database.DeleteAsync(item);
    }
}

Přístup k datům

Pokud používáte injektáž závislostí, můžete třídu TodoItemDatabase zaregistrovat jako singleton, který bude možné použít v celé aplikaci. Můžete například zaregistrovat své stránky a třídu přístupu k databázi jako služby objektu IServiceCollection , v MauiProgram.cs, pomocí AddSingleton a AddTransient metod:

builder.Services.AddSingleton<TodoListPage>();
builder.Services.AddTransient<TodoItemPage>();

builder.Services.AddSingleton<TodoItemDatabase>();

Tyto služby se pak dají automaticky vložit do konstruktorů tříd a přistupovat k těmto službám:

TodoItemDatabase database;

public TodoItemPage(TodoItemDatabase todoItemDatabase)
{
    InitializeComponent();
    database = todoItemDatabase;
}

async void OnSaveClicked(object sender, EventArgs e)
{
    if (string.IsNullOrWhiteSpace(Item.Name))
    {
        await DisplayAlert("Name Required", "Please enter a name for the todo item.", "OK");
        return;
    }

    await database.SaveItemAsync(Item);
    await Shell.Current.GoToAsync("..");
}

Alternativně je možné vytvořit nové instance třídy přístupu k databázi:

TodoItemDatabase database;

public TodoItemPage()
{
    InitializeComponent();
    database = new TodoItemDatabase();
}

Další informace o injektáži závislostí v aplikacích .NET MAUI najdete v tématu Injektáž závislostí.

Rozšířená konfigurace

SQLite poskytuje robustní rozhraní API s více funkcemi, než je popsáno v tomto článku a ukázkové aplikaci. Následující části se týkají funkcí, které jsou důležité pro škálovatelnost.

Další informace najdete v dokumentaci SQLite na sqlite.org.

Write-ahead logging

By default, SQLite uses a traditional rollback journal. Kopie nezměněného obsahu databáze se zapíše do samostatného souboru vrácení zpět a změny se zapíšou přímo do souboru databáze. The COMMIT occurs when the rollback journal is deleted.

Write-Ahead Logging (WAL) writes changes into a separate WAL file first. V režimu WAL je commit speciální záznam, připojený k souboru WAL, který umožňuje více transakcí nastat v jednom souboru WAL. Soubor WAL se sloučí zpět do databázového souboru ve speciální operaci označované jako kontrolní bod.

Wal může být rychlejší pro místní databáze, protože čtenáři a zapisovače navzájem neblokují, což umožňuje souběžné operace čtení a zápisu. Režim WAL ale neumožňuje změny velikosti stránky, přidá do databáze další přidružení souborů a přidá další operaci vytváření kontrolních bodů.

Pokud chcete v SQLite.NET povolit WAL, zavolejte EnableWriteAheadLoggingAsync metodu v SQLiteAsyncConnection instanci:

await Database.EnableWriteAheadLoggingAsync();

Další informace najdete v tématu SQLite Write-Ahead Logging on sqlite.org.

Kopírování databáze

Existuje několik případů, kdy může být nutné zkopírovat databázi SQLite:

• Databáze byla dodána s vaší aplikací, ale musí být zkopírována nebo přesunuta do zapisovatelného úložiště na mobilním zařízení.
• Potřebujete vytvořit zálohu nebo kopii databáze.
• Potřebujete vytvořit verzi, přesunout nebo přejmenovat soubor databáze.

Obecně platí, že přesouvání, přejmenování nebo kopírování souboru databáze je stejný proces jako jakýkoli jiný typ souboru s několika dalšími aspekty:

• Před pokusem o přesunutí souboru databáze by se měla zavřít všechna připojení k databázi.
• If you use Write-Ahead Logging, SQLite will create a Shared Memory Access (.shm) file and a (Write Ahead Log) (.wal) file. Ujistěte se, že u těchto souborů použijete také všechny změny.