Bancos de dados locais do .NET MAUI

Artigo
02/13/2024

O mecanismo de banco de dados SQLite permite que aplicativos .NET Multi-platform App UI (.NET MAUI) carreguem e salvem objetos de dados em código compartilhado. Você pode integrar SQLite.NET em aplicativos .NET MAUI, para armazenar e recuperar informações em um banco de dados local, seguindo estas etapas:

Instale o pacote NuGet.
Configurar constantes.
Crie uma classe de acesso ao banco de dados.
Dados de acesso.
Configuração avançada.

Este artigo usa o pacote NuGet sqlite-net-pcl para fornecer acesso ao banco de dados SQLite a uma tabela para armazenar itens todo. Uma alternativa é usar o pacote NuGet Microsoft.Data.Sqlite, que é um provedor de ADO.NET leve para SQLite. Microsoft.Data.Sqlite implementa as abstrações de ADO.NET comuns para funcionalidades, como conexões, comandos e leitores de dados.

Instalar o pacote NuGet do SQLite

Use o gerenciador de pacotes NuGet para procurar o pacote sqlite-net-pcl e adicionar a versão mais recente ao seu projeto de aplicativo .NET MAUI.

Há diversos pacotes NuGet com nomes semelhantes. O pacote correto tem estes atributos:

ID: sqlite-net-pcl
Autores: SQLite-net
Proprietários: praeclarum
Link do NuGet:sqlite-net-pcl

Apesar do nome do pacote, use o pacote NuGet sqlite-net-pcl em projetos .NET MAUI.

Importante

SQLite.NET é uma biblioteca de terceiros que é suportada pelo repositório praeclarum/sqlite-net.

Instalar SQLitePCLRaw.bundle_green

Além do sqlite-net-pcl, você precisa instalar temporariamente a dependência subjacente que expõe o SQLite em cada plataforma:

Identificação: SQLitePCLRaw.bundle_green
Versão:>= 2.1.0
Autores: Eric Sink
Proprietários: Eric Sink
Link do NuGet:SQLitePCLRaw.bundle_green

Configurar constantes de aplicativo

Os dados de configuração, como nome do arquivo e caminho do banco de dados, podem ser armazenados como constantes em seu aplicativo. O projeto de exemplo inclui um arquivo Constants.cs que fornece dados de configuração comuns:

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);
}

Neste exemplo, o arquivo de constantes especifica os valores de enum padrão SQLiteOpenFlag que são usados para inicializar a conexão de banco de dados. O SQLiteOpenFlag enum suporta estes valores:

Create: A conexão criará automaticamente o arquivo de banco de dados se ele não existir.
FullMutex: A conexão é aberta no modo de threading serializado.
NoMutex: A conexão é aberta no modo multi-threading.
PrivateCache: A conexão não participará do cache compartilhado, mesmo que esteja habilitada.
ReadWrite: A conexão pode ler e gravar dados.
SharedCache: A conexão participará do cache compartilhado, se estiver habilitada.
ProtectionComplete: O arquivo é criptografado e inacessível enquanto o dispositivo está bloqueado.
ProtectionCompleteUnlessOpen: O arquivo é criptografado até ser aberto, mas fica acessível mesmo se o usuário bloquear o dispositivo.
ProtectionCompleteUntilFirstUserAuthentication: O arquivo é criptografado até que o usuário tenha inicializado e desbloqueado o dispositivo.
ProtectionNone: O arquivo de banco de dados não está criptografado.

Talvez seja necessário especificar sinalizadores diferentes, dependendo de como o banco de dados será usado. Para obter mais informações sobre SQLiteOpenFlagso , consulte Abrindo uma nova conexão de banco de dados no sqlite.org.

Criar uma classe de acesso ao banco de dados

Uma classe wrapper de banco de dados abstrai a camada de acesso a dados do restante do aplicativo. Essa classe centraliza a lógica de consulta e simplifica o gerenciamento da inicialização do banco de dados, facilitando a refatoração ou a expansão das operações de dados à medida que o aplicativo cresce. O aplicativo de exemplo define uma TodoItemDatabase classe para essa finalidade.

Inicialização lenta

O TodoItemDatabase usa inicialização assíncrona lenta para atrasar a inicialização do banco de dados até que ele seja acessado pela primeira vez, com um método simples Init que é chamado por cada método na classe:

public class TodoItemDatabase
{
    SQLiteAsyncConnection Database;

    public TodoItemDatabase()
    {
    }

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

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

Métodos de manipulação de dados

A TodoItemDatabase classe inclui métodos para os quatro tipos de manipulação de dados: criar, ler, editar e excluir. A biblioteca SQLite.NET fornece um mapa relacional de objeto (ORM) simples que permite armazenar e recuperar objetos sem escrever instruções SQL.

O exemplo a seguir mostra os métodos de manipulação de dados no aplicativo de exemplo:

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);
    }
}

Acessar dados

A TodoItemDatabase classe pode ser registrada como um singleton que pode ser usado em todo o aplicativo se você estiver usando injeção de dependência. Por exemplo, você pode registrar suas páginas e a classe de acesso ao banco de dados como serviços no IServiceCollection objeto, em MauiProgram.cs, com os AddSingleton métodos e AddTransient :

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

builder.Services.AddSingleton<TodoItemDatabase>();

Esses serviços podem então ser injetados automaticamente em construtores de classe e acessados:

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("..");
}

Como alternativa, novas instâncias da classe de acesso ao banco de dados podem ser criadas:

TodoItemDatabase database;

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

Para obter mais informações sobre injeção de dependência em aplicativos .NET MAUI, consulte Injeção de dependência.

Configuração avançada

O SQLite fornece uma API robusta com mais recursos do que os abordados neste artigo e no aplicativo de exemplo. As seções a seguir abordam recursos importantes para escalabilidade.

Para obter mais informações, consulte Documentação do SQLite sobre sqlite.org.

Registro em log de gravação antecipada

Por padrão, o SQLite usa um diário de reversão tradicional. Uma cópia do conteúdo do banco de dados inalterado é gravada em um arquivo de reversão separado e, em seguida, as alterações são gravadas diretamente no arquivo de banco de dados. O COMMIT ocorre quando o diário de reversão é excluído.

O Write-Ahead Logging (WAL) grava as alterações em um arquivo WAL separado primeiro. No modo WAL, um COMMIT é um registro especial, anexado ao arquivo WAL, que permite que várias transações ocorram em um único arquivo WAL. Um arquivo WAL é mesclado novamente no arquivo de banco de dados em uma operação especial chamada ponto de verificação.

A WAL pode ser mais rápida para bancos de dados locais porque leitores e gravadores não bloqueiam uns aos outros, permitindo que as operações de leitura e gravação sejam simultâneas. No entanto, o modo WAL não permite alterações no tamanho da página, adiciona associações de arquivo adicionais ao banco de dados e adiciona a operação de checkpoint extra.

Para habilitar a WAL no SQLite.NET, chame o EnableWriteAheadLoggingAsyncSQLiteAsyncConnection método na instância:

await Database.EnableWriteAheadLoggingAsync();

Para obter mais informações, consulte SQLite Write-Ahead Logging on sqlite.org.

Copiar um banco de dados

Há vários casos em que pode ser necessário copiar um banco de dados SQLite:

Um banco de dados foi fornecido com seu aplicativo, mas deve ser copiado ou movido para o armazenamento gravável no dispositivo móvel.
Você precisa fazer um backup ou cópia do banco de dados.
Você precisa versão, mover ou renomear o arquivo de banco de dados.

Em geral, mover, renomear ou copiar um arquivo de banco de dados é o mesmo processo que qualquer outro tipo de arquivo com algumas considerações adicionais:

Todas as conexões de banco de dados devem ser fechadas antes de tentar mover o arquivo de banco de dados.
Se você usar o Write-Ahead Logging, o SQLite criará um arquivo de Acesso à Memória Compartilhada (.shm) e um arquivo (Log de Gravação Antecipada) (.wal). Certifique-se de aplicar quaisquer alterações a esses arquivos também.