Exercício: Armazenar dados localmente com o SQLite

  • 15 minutos

Neste exercício, você usa o SQLite para armazenar informações localmente com um aplicativo. No cenário de exemplo, você decidiu armazenar dados em cache para o aplicativo de rede social para melhorar a capacidade de resposta. Este exercício cria e usa um banco de dados SQLite local para armazenar informações sobre pessoas. Você salva o arquivo de banco de dados físico no armazenamento local.

Este módulo usa o SDK do .NET 8.0. Verifique se você tem o .NET 8.0 instalado executando o seguinte comando em seu terminal de comando preferencial:

dotnet --list-sdks

Uma saída semelhante ao seguinte exemplo aparece:

6.0.317 [C:\Program Files\dotnet\sdk]
7.0.401 [C:\Program Files\dotnet\sdk]
8.0.100 [C:\Program Files\dotnet\sdk]

Verifique se uma versão que começa com 8 está listada. Se nenhum estiver listado ou o comando não for encontrado, instale o SDK do .NET 8.0 mais recente.

Abrir a solução inicial

  1. Clone ou baixe o repositório do exercício.

    Observação

    É melhor clonar o conteúdo do exercício em um caminho de pasta curto, como C:\dev, para evitar que arquivos gerados por build excedam o comprimento máximo do caminho.

  2. Use o Visual Studio para abrir a solução People.sln, que você encontrará em mslearn-dotnetmaui-store-local-data>People ou na pasta inicial no Visual Studio Code.

    Observação

    Não tente compilar a solução ainda. O código está incompleto e não será compilado até que você adicione os elementos ausentes posteriormente neste exercício.

Definir uma entidade SQLite

  1. Clique com o botão direito do mouse no projeto People, selecione Adicionar e selecione Nova pasta para adicionar uma nova pasta ao projeto. Nomeie a nova pasta Modelos.

  2. Clique com o botão direito do mouse na pasta Modelos, selecione Adicionar e selecione Classe. Verifique se Classe está selecionada na lista e nomeie a nova classe Person.cs. Selecione Adicionar.

  3. Modifique a classe e marque-a como public:

    namespace People.Models
{

    public class Person
    {
    }
}

  4. Adicione uma propriedade int chamada Id à classe Person.

  5. Adicione uma propriedade string chamada Name. A classe deve ter esta aparência:

    namespace People.Models
{

    public class Person
    {
    public int Id { get; set; }
    public string Name { get; set; }
    }
}

  6. Salve o arquivo Person.cs.

Adicionar a biblioteca SQLite

  1. Clique com o botão direito do mouse no nó do projeto People no Gerenciador de Soluções no Visual Studio.

  2. No menu de contexto exibido, clique em Gerenciar pacotes NuGet.

  3. Pesquise e selecione sqlite-net-pcl e selecione Instalar.

    Uma captura de tela do gerenciador de pacotes NuGet com a biblioteca sqlite-net-pcl selecionada.

  4. Pesquise e selecione SQLitePCLRaw.bundle_green e, em seguida, selecione Instalar.

Se estiver usando o Visual Studio Code, abra o terminal e esses pacotes com os seguintes comandos:

dotnet add package sqlite-net-pcl
dotnet add package SQLitePCLRaw.bundle_green

Adicionar atributos do SQLite

  1. No arquivo Person.cs, adicione uma diretiva using para o namespace SQLite ao arquivo da classe Person. Essa diretiva permite que você use os atributos SQLite.

    using SQLite;

namespace People.Models
{

    public class Person
    ...
}

  2. Anote a classe Person com o atributo [Table] e especifique o nome da tabela como people.

  3. Especifique a propriedade Id como a chave primária. Anote-o com os atributos [PrimaryKey] e [AutoIncrement].

  4. Adicione anotações à propriedade Name. Especifique seu MaxLength como 250. Especifique que cada valor na coluna deve ser Unique.

    A classe concluída deverá ter esta aparência:

    using SQLite;

namespace People.Models
{

    [Table("people")]
    public class Person
    {
        [PrimaryKey, AutoIncrement]
        public int Id { get; set; }

        [MaxLength(250), Unique]
        public string Name { get; set; }
    }
}

  5. Salve o arquivo Person.cs.

Conectar-se ao banco de dados

  1. Abra o arquivo PersonRepository.cs.

  2. Examine a classe PersonRepository. Essa classe contém o esqueleto do código incompleto com marcadores TODO em que você adiciona a funcionalidade para acessar o banco de dados.

  3. Adicione uma diretiva using para os namespaces SQLite e People.Models ao arquivo para a classe PersonRepository.cs.

  4. Adicione um campo privado SQLiteConnection nomeado conn à classe, acima da função Init.

  5. Na função Init, verifique se conn não é igual a null. Nesse caso, retorne imediatamente.

    if (conn != null)
    return;

    Dessa forma, o código de inicialização do banco de dados SQLite é executado apenas uma vez.

  6. Inicialize o campo conn para se conectar ao banco de dados usando a variável _dbPath.

  7. Use o método conn.CreateTable para criar uma tabela para armazenar dados Person. A função Init concluída deve ter esta aparência:

    using SQLite;
using People.Models;
...

private SQLiteConnection conn;
...
private void Init()
{
   if (conn != null)
      return;

   conn = new SQLiteConnection(_dbPath);
   conn.CreateTable<Person>();
}

Inserir uma linha no banco de dados

  1. Na classe PersonRepository, localize o método AddNewPerson.

  2. Para inserir um novo objeto Person, substitua o comentário TODO neste método pelo código. O código primeiro chama Init para verificar se o banco de dados é inicializado e, em seguida, usa o método SQLiteConnection do objeto Insert. Defina a variável result como o valor que o método Insert retorna, conforme mostrado no seguinte código:

    public void AddNewPerson(string name)
{
    int result = 0;
    try
    {
        // enter this line
        Init();

        // basic validation to ensure a name was entered
        if (string.IsNullOrEmpty(name))
            throw new Exception("Valid name required");

        // enter this line
        result = conn.Insert(new Person { Name = name });
        ...
    }
    ...
}

Recuperar linhas do banco de dados

  1. Na classe PersonRepository localize o método GetAllPeople.

  2. Chame Init para verificar se o banco de dados está inicializado.

  3. Use o método genérico Table\<T> para recuperar todas as linhas na tabela. Especifique Person como o parâmetro de tipo.

  4. Use o método de extensão ToList() para transformar o resultado em uma coleção List\<Person> e retornar essa coleção.

  5. Adicione o tratamento de erro encapsulando seu código em um bloco try-catch. Se houver um erro, defina a propriedade StatusMessage como a propriedade Message da exceção e retorne uma coleção vazia. O método completo deverá ter esta aparência:

    public List<Person> GetAllPeople()
{
   try
   {
      Init();
      return conn.Table<Person>().ToList();
   }
   catch (Exception ex)
   {
      StatusMessage = string.Format("Failed to retrieve data. {0}", ex.Message);
   }

   return new List<Person>();
}

  6. Salve o arquivo PersonRepository.cs.

Integrar o repositório à interface do usuário

  1. Abra o arquivo MauiProgram.cs.

  2. Na função CreateMauiApp, após as instruções que adicionam a página MainPage como um serviço singleton ao aplicativo, adicione código para executar as seguintes tarefas:

    • Crie uma variável de cadeia de caracteres chamada dbPath. Inicialize essa cadeia de caracteres com a expressão FileAccessHelper.GetLocalFilePath("people.db3"). O arquivo de banco de dados usado pelo aplicativo é chamado people.db3, e o aplicativo salva esse arquivo no armazenamento local no dispositivo.

    • Use a injeção de dependência para adicionar a classe PersonRepository como um serviço singleton ao aplicativo. A classe PersonRepository expõe um construtor que usa o caminho para o arquivo de banco de dados como um parâmetro de cadeia de caracteres.

    O código concluído para a função CreateMauiApp deve ter esta aparência:

    public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
        .ConfigureFonts(fonts =>
        {
            fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
        });

    // Add this code
    string dbPath = FileAccessHelper.GetLocalFilePath("people.db3");
    builder.Services.AddSingleton<PersonRepository>(s => ActivatorUtilities.CreateInstance<PersonRepository>(s, dbPath));

    return builder.Build();
}

  3. Salve o arquivo MauiProgram.cs.

  4. Expanda App.xaml no Gerenciador de Soluções e abra o arquivo App.xaml.cs.

  5. Adicione uma propriedade public, static chamada PersonRepo. Essa propriedade contém um objeto PersonRepository para a classe App.

  6. Inicialize a propriedade PersonRepo no construtor adicionando um parâmetro PersonRepository ao construtor e definindo a propriedade "PersonRepo" como o valor neste parâmetro. A classe App concluída deve ter esta aparência:

    public partial class App : Application
{
    public static PersonRepository PersonRepo { get; private set; }

    public App(PersonRepository repo)
    {
        InitializeComponent();

        MainPage = new AppShell();

        PersonRepo = repo;
    }
}

Observação

O processo de injeção de dependência preenche automaticamente o parâmetro repo para o construtor.

Testar o aplicativo

  1. Compile a solução, pressionando CTRL+SHIFT+B.

  2. Depois que a compilação for concluída, inicie a depuração usando F5. Quando a interface do usuário for exibida, insira seu nome e selecione Adicionar Pessoa.

    Uma captura de tela do aplicativo com uma mensagem bem-sucedida informando que um registro foi adicionado.

  3. Selecione Obter Todas as Pessoas e verifique se seu nome aparece.

    Captura de tela do aplicativo com uma lista de todos os registros no banco de dados.

  4. Experimente adicionando mais nomes e recuperando a lista de pessoas armazenadas.

  5. Retorne ao Visual Studio ou ao Visual Studio Code e interrompa a depuração usando Shift+F5.

  6. Reinicie o aplicativo e selecione Obter Todas as Pessoas. Verifique se os nomes armazenados anteriormente ainda estão armazenados no banco de dados. Feche o aplicativo quando terminar.