Tutorial: Criar um aplicativo de banco de dados do cliente

2025-06-10

Este tutorial cria um aplicativo simples para gerenciar uma lista de clientes. Ao fazer isso, ele apresenta uma seleção de conceitos básicos para aplicativos empresariais na UWP. Você aprenderá a:

Implemente operações criar, ler, atualizar e excluir em um banco de dados SQL local.
Adicione uma grade de dados para exibir e editar dados do cliente na interface do usuário.
Organize os elementos de interface do usuário em um layout de formulário básico.

O ponto de partida deste tutorial é um aplicativo de página única com interface e funcionalidade mínimas, baseado em uma versão simplificada do aplicativo de exemplo de banco de dados de Pedidos de Cliente . Ele é escrito em C# e XAML, e esperamos que você tenha uma familiaridade básica com essas duas linguagens.

A página principal do aplicativo de trabalho

Pré-requisitos

Depois de clonar/baixar o repositório, você pode editar o projeto abrindo CustomerDatabaseTutorial.sln com o Visual Studio.

Observação

Este tutorial baseia-se no de exemplo do Banco de Dados de Pedidos de Clientes do , que foi atualizado recentemente para usar o WinUI e o SDK do Aplicativo windows. Até que este tutorial e código sejam atualizados, haverá diferenças entre os dois exemplos.

Parte 1: Código de Interesse

Se você executar seu aplicativo imediatamente após abri-lo, verá alguns botões na parte superior de uma tela em branco. Embora não esteja visível para você, o aplicativo já inclui um banco de dados SQLite local provisionado com alguns clientes de teste. A partir daqui, você começará implementando um controle de interface do usuário para exibir esses clientes e, em seguida, passará a adicionar operações no banco de dados. Antes de começar, aqui é onde você estará trabalhando.

Visões

CustomerListPage.xaml é a visão do aplicativo, que define a interface do usuário para a página única deste tutorial. Sempre que precisar adicionar ou alterar um elemento visual na interface do usuário, você o fará neste arquivo. Este tutorial orientará você na adição desses elementos:

Um RadDataGrid para visualização e edição dos seus clientes.
Um StackPanel para definir os valores iniciais para um novo cliente.

ViewModels

ViewModels\CustomerListPageViewModel.cs é onde a lógica fundamental do aplicativo está localizada. Todas as ações do usuário executadas na exibição serão passadas para este arquivo para processamento. Neste tutorial, você adicionará um novo código e implementará os seguintes métodos:

CreateNewCustomerAsync, que inicializa um novo objeto CustomerViewModel.
DeleteNewCustomerAsync, que remove um novo cliente antes de ele ser exibido na interface do usuário.
DeleteAndUpdateAsync, que manipula a lógica do botão de exclusão.
GetCustomerListAsync, que recupera uma lista de clientes do banco de dados.
SaveInitialChangesAsync, que adiciona as informações de um novo cliente ao banco de dados.
UpdateCustomersAsync, que atualiza a interface do usuário para refletir os clientes adicionados ou excluídos.

CustomerViewModel é um wrapper para as informações de um cliente, que controla se foram modificadas recentemente ou não. Você não precisará adicionar nada a essa classe, mas parte do código que você adicionará em outro lugar fará referência a ela.

Para obter mais informações sobre como o exemplo é construído, confira a visão geral da estrutura do aplicativo.

Parte 2: Adicionar o DataGrid

Antes de começar a operar nos dados do cliente, você precisará adicionar um controle de interface do usuário para exibir esses clientes. Para fazer isso, usaremos um controle de terceiros RadDataGrid, que é pré-fabricado. O pacote Telerik.UI.for.UniversalWindowsPlatform NuGet já foi incluído neste projeto. Vamos adicionar a grade de dados ao nosso projeto.

Abra Views\CustomerListPage.xaml no Gerenciador de Soluções. Adicione a seguinte linha de código na tag Page para declarar um mapeamento para o namespace Telerik que contém o grid de dados.
```
    xmlns:telerikGrid="using:Telerik.UI.Xaml.Controls.Grid"
```

Abaixo do CommandBar no RelativePanel principal do Modo de Exibição, adicione um controle RadDataGrid, com algumas opções básicas de configuração.

<Grid
    x:Name="CustomerListRoot"
    Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
    <RelativePanel>
        <CommandBar
            x:Name="mainCommandBar"
            HorizontalAlignment="Stretch"
            Background="AliceBlue">
            <!--CommandBar content-->
        </CommandBar>
        <telerikGrid:RadDataGrid
            x:Name="DataGrid"
            BorderThickness="0"
            ColumnDataOperationsMode="Flyout"
            GridLinesVisibility="None"
            GroupPanelPosition="Left"
            RelativePanel.AlignLeftWithPanel="True"
            RelativePanel.AlignRightWithPanel="True"
            RelativePanel.Below="mainCommandBar" />
    </RelativePanel>
</Grid>

Você adicionou a grade de dados, mas ela precisa de dados a serem exibidos. Adicione as seguintes linhas de código a ele:
```
ItemsSource="{x:Bind ViewModel.Customers}"
UserEditMode="Inline"
```
Agora que você definiu uma fonte de dados a ser exibida, o RadDataGrid manipulará a maior parte da lógica da interface do usuário para você. No entanto, se você executar seu projeto, ainda não verá nenhum dado em exibição. Isso ocorre porque o ViewModel ainda não o está carregando.

Parte 3: Compreender clientes

Quando inicializado, ViewModels\CustomerListPageViewModel.cs chama o método GetCustomerListAsync . Esse método precisa recuperar os dados do cliente de teste do banco de dados SQLite incluído no tutorial.

Em ViewModels\CustomerListPageViewModel.cs, atualize o método GetCustomerListAsync com este código:
```
public async Task GetCustomerListAsync()
{
    var customers = await App.Repository.Customers.GetAsync(); 
    if (customers == null)
    {
        return;
    }
    await DispatcherHelper.ExecuteOnUIThreadAsync(() =>
    {
        Customers.Clear();
        foreach (var c in customers)
        {
            Customers.Add(new CustomerViewModel(c));
        }
    });
}
```
O método GetCustomerListAsync é chamado quando o ViewModel é carregado, mas antes desta etapa, ele não fez nada. Aqui, adicionamos uma chamada ao método GetAsync no Repository/SqlCustomerRepository. Isso permite que ele entre em contato com o repositório para recuperar uma coleção enumerável de objetos Customer. Em seguida, analisa-os em objetos individuais, antes de adicioná-los ao ObservableCollection para que possam ser exibidos e editados.
Execute seu aplicativo – agora você verá a grade de dados exibindo a lista de clientes.

Lista inicial de clientes

Parte 4: Editar clientes

Você pode editar as entradas na grade de dados clicando duas vezes nelas, mas precisa garantir que todas as alterações feitas na interface do usuário também sejam refletidas na sua coleção de clientes no code-behind. Isso significa que você precisará implementar a associação de dados bidirecional. Se você quiser mais informações sobre isso, confira nossa introdução à associação de dados.

Primeiro, declare que ViewModels\CustomerListPageViewModel.cs implementa a interface INotifyPropertyChanged
```
public class CustomerListPageViewModel : INotifyPropertyChanged
```
Em seguida, dentro do corpo principal da classe, adicione o seguinte evento e método:
```
public event PropertyChangedEventHandler PropertyChanged;

public void OnPropertyChanged([CallerMemberName] string propertyName = null) =>
    PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
```
O método OnPropertyChanged torna mais fácil para os setters acionar o evento PropertyChanged, que é necessário para associação de dados bidirecional.

Atualize o setter para SelectedCustomer com esta chamada de função:

public CustomerViewModel SelectedCustomer
{
    get => _selectedCustomer;
    set
    {
        if (_selectedCustomer != value)
        {
            _selectedCustomer = value;
            OnPropertyChanged();
        }
    }
}

Em Views\CustomerListPage.xaml, adicione a propriedade SelectedCustomer à grade de dados.
```
SelectedItem="{x:Bind ViewModel.SelectedCustomer, Mode=TwoWay}"
```
Isso associa a seleção do usuário na grade de dados ao objeto Cliente correspondente no code-behind. O modo de associação TwoWay permite que as alterações feitas na interface do usuário sejam refletidas nesse objeto.
Execute seu aplicativo. Agora você pode ver os clientes exibidos na grade e fazer alterações nos dados subjacentes por meio da interface do usuário.

Editando um cliente na grade de dados

Parte 5: Atualizar clientes

Agora que você pode ver e editar seus clientes, precisará ser capaz de gravar suas alterações no banco de dados e obter todas as atualizações que foram feitas por outras pessoas.

Retorne a ViewModels\CustomerListPageViewModel.cs e navegue até o método UpdateCustomersAsync . Atualize-o com esse código, para enviar alterações por push para o banco de dados e para recuperar novas informações:
```
public async Task UpdateCustomersAsync()
{
    foreach (var modifiedCustomer in Customers
        .Where(x => x.IsModified).Select(x => x.Model))
    {
        await App.Repository.Customers.UpsertAsync(modifiedCustomer);
    }
    await GetCustomerListAsync();
}
```
Esse código utiliza a propriedade IsModified de ViewModels\CustomerViewModel.cs, que é atualizada automaticamente sempre que o cliente é alterado. Isso permite que você evite chamadas desnecessárias e envie apenas alterações por push de clientes atualizados para o banco de dados.

Parte 6: Criar um novo cliente

Adicionar um cliente novo apresenta um desafio, pois este aparecerá como uma linha vazia se você inseri-lo na UI antes de fornecer valores para suas propriedades. Isso não é um problema, mas aqui facilitaremos a definição dos valores iniciais de um cliente. Neste tutorial, adicionaremos um painel recolhível simples, mas se você tiver mais informações para adicionar, poderá criar uma página separada para essa finalidade.

Atualizar o code-behind (código subjacente)

Adicione um novo campo privado e uma propriedade pública a ViewModels\CustomerListPageViewModel.cs. Isso será usado para controlar se o painel está visível ou não.

private bool _addingNewCustomer = false;

public bool AddingNewCustomer
{
    get => _addingNewCustomer;
    set
    {
        if (_addingNewCustomer != value)
        {
            _addingNewCustomer = value;
            OnPropertyChanged();
        }
    }
}

Adicione uma nova propriedade pública ao ViewModel, um inverso do valor de AddingNewCustomer. Isso será usado para desabilitar os botões da barra de comandos regulares quando o painel estiver visível.
```
public bool EnableCommandBar => !AddingNewCustomer;
```
Agora você precisará de uma maneira de exibir o painel recolhível e criar um cliente para editar dentro dele.

Adicione um novo fiend privado e uma propriedade pública ao ViewModel para manter o cliente recém-criado.

private CustomerViewModel _newCustomer;

public CustomerViewModel NewCustomer
{
    get => _newCustomer;
    set
    {
        if (_newCustomer != value)
        {
            _newCustomer = value;
            OnPropertyChanged();
        }
    }
}

Atualize o método CreateNewCustomerAsync para criar um novo cliente, adicione-o ao repositório e defina-o como o cliente selecionado:

public async Task CreateNewCustomerAsync()
{
    CustomerViewModel newCustomer = new CustomerViewModel(new Models.Customer());
    NewCustomer = newCustomer;
    await App.Repository.Customers.UpsertAsync(NewCustomer.Model);
    AddingNewCustomer = true;
}

Atualize o método SaveInitialChangesAsync para adicionar um cliente recém-criado ao repositório, atualize a interface do usuário e feche o painel.

public async Task SaveInitialChangesAsync()
{
    await App.Repository.Customers.UpsertAsync(NewCustomer.Model);
    await UpdateCustomersAsync();
    AddingNewCustomer = false;
}

Adicione a seguinte linha de código como a linha final no setter para AddingNewCustomer:
```
OnPropertyChanged(nameof(EnableCommandBar));
```
Isso garantirá que EnableCommandBar seja atualizado automaticamente sempre que AddingNewCustomer for alterado.

Atualizar a interface do usuário

Navegue de volta para Views\CustomerListPage.xamle adicione um StackPanel com as seguintes propriedades entre o CommandBar e a sua grade de dados:
```
<StackPanel
    x:Name="newCustomerPanel"
    Orientation="Horizontal"
    x:Load="{x:Bind ViewModel.AddingNewCustomer, Mode=OneWay}"
    RelativePanel.Below="mainCommandBar">
</StackPanel>
```
O atributo x:Load garante que esse painel só apareça quando você estiver adicionando um novo cliente.
Faça a seguinte alteração na posição da grade de dados para garantir que ela se mova para baixo quando o novo painel for exibido:
```
RelativePanel.Below="newCustomerPanel"
```

Atualize o painel de pilha com quatro controles TextBox. Eles serão associados às propriedades individuais do novo cliente e permitirão que você edite seus valores antes de adicioná-lo à grade de dados.

<StackPanel
    x:Name="newCustomerPanel"
    Orientation="Horizontal"
    x:Load="{x:Bind ViewModel.AddingNewCustomer, Mode=OneWay}"
    RelativePanel.Below="mainCommandBar">
    <TextBox
        Header="First name"
        PlaceholderText="First"
        Margin="8,8,16,8"
        MinWidth="120"
        Text="{x:Bind ViewModel.NewCustomer.FirstName, Mode=TwoWay, UpdateSourceTrigger=PropertyChanged}"/>
    <TextBox
        Header="Last name"
        PlaceholderText="Last"
        Margin="0,8,16,8"
        MinWidth="120"
        Text="{x:Bind ViewModel.NewCustomer.LastName, Mode=TwoWay, UpdateSourceTrigger=PropertyChanged}"/>
    <TextBox
        Header="Address"
        PlaceholderText="1234 Address St, Redmond WA 00000"
        Margin="0,8,16,8"
        MinWidth="280"
        Text="{x:Bind ViewModel.NewCustomer.Address, Mode=TwoWay, UpdateSourceTrigger=PropertyChanged}"/>
    <TextBox
        Header="Company"
        PlaceholderText="Company"
        Margin="0,8,16,8"
        MinWidth="120"
        Text="{x:Bind ViewModel.NewCustomer.Company, Mode=TwoWay, UpdateSourceTrigger=PropertyChanged}"/>
</StackPanel>

Adicione um botão simples ao seu novo StackPanel para salvar o cliente recém-criado.

<StackPanel>
    <!--Text boxes from step 3-->
    <AppBarButton
        x:Name="SaveNewCustomer"
        Click="{x:Bind ViewModel.SaveInitialChangesAsync}"
        Icon="Save"/>
</StackPanel>

Atualize o CommandBar, para que os botões regulares de criação, exclusão e atualização fiquem desabilitados quando o painel de pilha estiver visível.

<CommandBar
    x:Name="mainCommandBar"
    HorizontalAlignment="Stretch"
    IsEnabled="{x:Bind ViewModel.EnableCommandBar, Mode=OneWay}"
    Background="AliceBlue">
    <!--App bar buttons-->
</CommandBar>

Execute seu aplicativo. Agora você pode criar um cliente e inserir seus dados no painel de stack.

Criando um novo cliente

Parte 7: Excluir um cliente

Excluir um cliente é a operação básica final que você precisa implementar. Ao excluir um cliente selecionado na grade de dados, você desejará chamar imediatamente UpdateCustomersAsync para atualizar a interface do usuário. No entanto, você não precisará chamar esse método se estiver excluindo um cliente que acabou de criar.

Navegue até ViewModels\CustomerListPageViewModel.cse atualize o método DeleteAndUpdateAsync :

public async void DeleteAndUpdateAsync()
{
    if (SelectedCustomer != null)
    {
        await App.Repository.Customers.DeleteAsync(_selectedCustomer.Model.Id);
    }
    await UpdateCustomersAsync();
}

Em Views\CustomerListPage.xaml, atualize o painel em pilha para adicionar um novo cliente de modo que contenha um segundo botão:

<StackPanel>
    <!--Text boxes for adding a new customer-->
    <AppBarButton
        x:Name="DeleteNewCustomer"
        Click="{x:Bind ViewModel.DeleteNewCustomerAsync}"
        Icon="Cancel"/>
    <AppBarButton
        x:Name="SaveNewCustomer"
        Click="{x:Bind ViewModel.SaveInitialChangesAsync}"
        Icon="Save"/>
</StackPanel>

Em ViewModels\CustomerListPageViewModel.cs, atualize o método DeleteNewCustomerAsync para excluir o novo cliente:

public async Task DeleteNewCustomerAsync()
{
    if (NewCustomer != null)
    {
        await App.Repository.Customers.DeleteAsync(_newCustomer.Model.Id);
        AddingNewCustomer = false;
    }
}

Execute seu aplicativo. Agora você pode excluir clientes, dentro da grade de dados ou no painel de pilha.

Excluir um novo cliente

Conclusão

Parabéns! Com tudo isso feito, seu aplicativo agora tem uma gama completa de operações de banco de dados local. Você pode criar, ler, atualizar e excluir clientes em sua interface do usuário, e essas alterações são salvas em seu banco de dados e persistirão em diferentes inicializações do seu aplicativo.

Agora que você terminou, considere o seguinte:

Se você ainda não fez isso, confira a visão geral da estrutura do aplicativo para obter mais informações sobre por que o aplicativo é criado como ele é.
Explore o exemplo completo do Banco de Dados de Pedidos de Clientes para ver o aplicativo no qual este tutorial foi baseado.

Ou se você está afim de um desafio, você pode continuar...

Indo mais longe: conectar-se a um banco de dados remoto

Fornecemos um passo a passo de como implementar essas chamadas em um banco de dados SQLite local. Mas e se você quiser usar um banco de dados remoto?

Se você quiser experimentar isso, precisará de sua própria conta do AAD (Azure Active Directory) e da capacidade de hospedar sua própria fonte de dados.

Você precisará adicionar autenticação, funções para lidar com chamadas REST e criar um banco de dados remoto com o qual interagir. Há um código no exemplo completo do Banco de Dados de Pedidos de Clientes que você pode referenciar para cada operação necessária.

Ajustes e configurações

As etapas necessárias para se conectar ao seu próprio banco de dados remoto estão detalhadas no arquivo readme do exemplo . Será necessário fazer o seguinte:

Forneça o ID do cliente da sua conta do Azure para Constants.cs.
Forneça a URL do banco de dados remoto para Constants.cs.
Forneça a string de conexão do banco de dados para Constants.cs.
Associe seu aplicativo à Microsoft Store.
Copie o projeto de serviço em seu aplicativo e implante-o no Azure.

Autenticação

Você precisará criar um botão para iniciar uma sequência de autenticação e um pop-up ou uma página separada para coletar as informações de um usuário. Depois de criar isso, você precisará fornecer um código que solicite as informações de um usuário e as use para adquirir um token de acesso. O exemplo de Banco de Dados de Pedidos de Clientes encapsula chamadas do Microsoft Graph com a biblioteca WebAccountManager para adquirir um token e gerenciar a autenticação para uma conta do AAD.

A lógica de autenticação é implementada em AuthenticationViewModel.cs.
O processo de autenticação é exibido no controle personalizado AuthenticationControl.xaml.

Chamadas REST

Você não precisará modificar nenhum dos códigos que adicionamos neste tutorial para implementar chamadas REST. Em vez disso, você precisará fazer o seguinte:

Crie novas implementações das interfaces ICustomerRepository e ITutorialRepository, implementando o mesmo conjunto de funções por meio de REST em vez de SQLite. Você precisará serializar e desserializar o JSON e pode encapsular suas chamadas REST em uma classe HttpHelper separada, se necessário. Consulte o exemplo completo para obter detalhes.
Em App.xaml.cs, crie uma nova função para inicializar o repositório REST e chame-a em vez de SqliteDatabase quando o aplicativo for inicializado. Novamente, consulte o exemplo completo.

Depois que todas essas três etapas forem concluídas, você poderá autenticar sua conta do AAD por meio de seu aplicativo. As chamadas REST para o banco de dados remoto substituirão as chamadas SQLite locais, mas a experiência do usuário deve ser a mesma. Se você estiver se sentindo ainda mais ambicioso, poderá adicionar uma página de configurações para permitir que o usuário alterne dinamicamente entre os dois.