Building a CRUD Web API with Dataverse Entities in ASP.NET Web API: A Beginner's Guide

Construindo uma API Web CRUD com entidades Dataverse na API Web ASP.NET: um guia para iniciantes

4 de outubro de 2024 Pedro Martins

Introdução

No desenvolvimento de aplicativos modernos, a integração com plataformas de dados robustas é essencial para escalabilidade e flexibilidade. O Microsoft Dataverse (anteriormente conhecido como Common Data Service) fornece uma opção de armazenamento segura e baseada em nuvem para seus dados, atuando como a plataforma de dados subjacente para aplicativos Microsoft Power Platform e Dynamics 365.

Neste tutorial, vamos orientá-lo na criação de uma API Web CRUD (Create, Read, Update, Delete) usando uma entidade Dataverse na API Web ASP.NET . Este guia passo a passo foi criado para programadores iniciantes, oferecendo explicações detalhadas e exemplos de código.

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte:

Visual Studio 2022 (Community Edition é suficiente)
.NET 6 SDK ou posterior
Um ambiente Dataverse ativo (disponível por meio de uma avaliação do Power Apps)
Conhecimento básico de C# e .NET
Acesso ao Azure Active Directory (Azure AD) (para registro de aplicativo)
Pacote NuGet Microsoft.PowerPlatform.Dataverse.Client

Índice

Configurando o ambiente de desenvolvimento
Criando uma entidade do Dataverse
Criando o projeto ASP .NET Web API
Conectando- se ao Dataverse a partir da API da Web
Implementando Operações CRUD
Testando a API
Conclusão

1. Configurando o ambiente de desenvolvimento

Instalar o Visual Studio 2022

Baixe e instale o Visual Studio 2022 Community Edition do site oficial .
Durante a instalação, selecione as seguintes cargas de trabalho:
- ASP.NET e desenvolvimento web
- Desenvolvimento de desktop .NET

Instalar o SDK do .NET 6

Baixe e instale o .NET 8 SDK na página de downloads do .NET .

Configurar um ambiente Dataverse

Inscreva-se para uma avaliação gratuita do Power Apps se você ainda não tiver um ambiente.
Acesse o portal do Power Apps em https://make.powerapps.com/ .

2. Criando uma entidade Dataverse

Acesse o Dataverse no Power Apps

Navegue até Dataverse > Tabelas no menu à esquerda.

Criar uma nova tabela (entidade)

Clique em + Nova tabela .
Configure a nova tabela:
- Nome de exibição : Student
- Nome de exibição plural : Students
- Coluna primária : Student Name
- Clique em Criar .

Adicionar colunas à tabela

Adicione as seguintes colunas à tabela Student :

Idade
- Tipo de dados : Número (número inteiro)
E-mail
- Tipo de dados : Texto
Data de inscrição
- Tipo de dados : Data e hora (somente data)

Salve a tabela depois de adicionar todas as colunas.

3. Criando o projeto ASP.NET Web API

Criar um novo projeto

Abra o Visual Studio 2022 .
Clique em Criar um novo projeto .
Selecione ASP.NET Core Web API .
Clique em Avançar .

Configurar o Projeto

Nome do projeto : DataverseWebApi
Localização : Escolha seu diretório preferido.
Clique em Avançar .

Definir informações adicionais

Framework : .NET 8.0 (Long-term support)
Tipo de autenticação : Nenhum
Habilitar suporte OpenAPI : Verificado (para Swagger UI)
Clique em Criar .

4. Conectando-se ao Dataverse a partir da API da Web

Para interagir com o Dataverse, usaremos o pacote Microsoft.PowerPlatform.Dataverse.Client NuGet.

Instalar o pacote NuGet

Clique com o botão direito do mouse no projeto no Solution Explorer .
Selecione Gerenciar pacotes NuGet .
Vá para a guia Procurar e procure por Microsoft.PowerPlatform.Dataverse.Client .
Instale a versão estável mais recente.

Registrar um aplicativo no Azure AD

Acesse o Portal do Azure .
Navegue até Azure Active Directory > Registros de aplicativos .
Clique em Novo registro .
- Nome : DataverseWebApiApp
- Tipos de contas com suporte : Contas somente neste diretório organizacional
- URI de redirecionamento : https://localhost
- Clique em Registrar .
Anote o ID do aplicativo (cliente) .
Em Certificates & secrets , crie um novo segredo de cliente. Anote-o.

Adicionar string de conexão ao appsettings.json

Abra appsettings.json e adicione sua string de conexão do Dataverse:

json

{ "Strings de conexão" : { "Dataverse" : "AuthType=ClientSecret;Url=https://yourorg.crm.dynamics.com;ClientId=seu_id_cliente;ClientSecret=seu_segredo_cliente;LoginPrompt=Auto" } }

Substitua https://yourorg.crm.dynamics.com pelo URL da sua organização do Dataverse.
Substitua your_client_id e your_client_secret pelos valores do Azure AD.

Observação de segurança : para produção, use métodos seguros como o Azure Key Vault para armazenar segredos.

5. Implementando Operações CRUD

Crie um modelo para o aluno

Crie uma pasta Models . Adicione uma nova classe Student.cs :

c sustenido

using System;

 namespace DataverseWebApi.Models
 {
 public class Student
 {
 public Guid Id { get ; set ; }
 public string StudentName { get ; set ; }
 public int Age { get ; set ; }
 public string Email { get ; set ; }

data e hora públicas Data de inscrição { obter ; definir ;} } }

Crie um serviço para interagir com o Dataverse

Crie uma pasta Services . Adicione uma nova classe DataverseService.cs :

c sustenido

using Microsoft.PowerPlatform.Dataverse.Client;
 using Microsoft.Xrm.Sdk;
 using Microsoft.Xrm.Sdk.Query;
 using System;
 using System.Collections.Generic;
 using System.Threading.Tasks;
 using DataverseWebApi.Models;
 using Microsoft.Extensions.Configuration;

namespace DataverseWebApi.Services { classe pública DataverseService { privado somente leitura ServiceClient _serviceClient; public DataverseService ( configuração IConfiguration ) { var connectionString = configuração.GetConnectionString( "Dataverse" ); _serviceClient = novo ServiceClient(connectionString); } public async Task<Guid> CreateStudentAsync ( Aluno aluno ) { var entity = new Entity( "student" ); // Substitua pelo nome lógico da sua entidade entidade[ "nome do aluno" ] = aluno.Nome do Aluno; entidade[ "idade" ] = aluno.Idade; entidade[ "email" ] = aluno.Email; entity[ "datamatrícula" ] = aluno.Datamatrícula; retornar await Task.Run(() => _serviceClient.Create(entidade)); } public async Task<Aluno> GetStudentAsync ( Guid id ) { var colunas = new ColumnSet( "nome do aluno" , "idade" , "e-mail" , "data de inscrição" ); var entidade = await Task.Run(() => _serviceClient.Retrieve( "aluno" , id, colunas)); se (entidade == nulo ) retornar nulo ; retornar novo aluno { Id = entidade.Id, Nome do Aluno = entidade.GetAttributeValue< string >( "nome do aluno" ), Idade = entidade.GetAttributeValue< int >( "idade" ), E-mail = entidade.GetAttributeValue< string >( "e-mail" ), DataInscrição = entidade.GetAttributeValue<DataHora>( "datainscrição" ) }; } public async Tarefa UpdateStudentAsync ( Aluno aluno ) { var entidade = nova Entidade( "aluno" , aluno.Id); entidade[ "nome do aluno" ] = aluno.Nome do Aluno; entidade[ "idade" ] = aluno.Idade; entidade[ "email" ] = aluno.Email; entity[ "datamatrícula" ] = aluno.Datamatrícula; aguarde Task.Run(() => _serviceClient.Update(entidade)); } tarefa pública assíncrona DeleteStudentAsync ( Guid id ) { aguarde Task.Run(() => _serviceClient.Delete( "aluno" , id)); } public async Tarefa<Lista<Aluno>> GetStudentsAsync() { var query = new QueryExpression( "aluno" ) { ColumnSet = new ColumnSet( "nome do aluno" , "idade" , "e-mail" , "data de inscrição" ) }; var entidades = await Task.Run(() => _serviceClient.RetrieveMultiple(query)); var alunos = nova Lista<Aluno>(); foreach ( var entidade em entidades.Entidades) { alunos.Adicionar( novo aluno { Id = entidade.Id, Nome do Aluno = entidade.GetAttributeValue< string >( "nome do aluno" ), Idade = entidade.GetAttributeValue< int >( "idade" ), E-mail = entidade.GetAttributeValue< string >( "e-mail" ), DataInscrição = entidade.GetAttributeValue<DataHora>( "datainscrição" ) }); } alunos que retornam ; } } }

Explicação :

Nomes lógicos de entidades : substitua "student" , "studentname" , etc., pelos nomes lógicos de entidades reais do Dataverse.
ServiceClient : gerencia a conexão com o Dataverse.

Registre o serviço em injeção de dependência

Em Program.cs , adicione:

c sustenido

builder.Services.AddSingleton<DataverseService>();

Crie o StudentsController

Crie um novo controlador StudentsController.cs na pasta Controllers :

c sustenido

using DataverseWebApi.Models;
 using DataverseWebApi.Services;
 using Microsoft.AspNetCore.Mvc;
 using System;
 using System.Collections.Generic;
 using System.Threading.Tasks;

 namespace DataverseWebApi.Controllers
 {

[ Rota( "api/[controlador]" ) ] [ ApiController ] classe pública StudentsController : ControllerBase { privado somente leitura DataverseService _dataverseService; Public StudentsController ( DataverseService dataverseService ) { _dataverseService = dataverseService; } // OBTER: api/Alunos [ HttpGet ] pública assíncrona Task<ActionResult<IEnumerable<Aluno>>> GetStudents() { var estudantes = aguardar _dataverseService.GetStudentsAsync(); retornar Ok(alunos); } // OBTER: api/Alunos/{id} [ HttpGet( "{id}" ) ] pública assíncrona Task<ActionResult<Aluno>> GetStudent(Guid id) { var estudante = aguarda _dataverseService.GetStudentAsync(id); se (aluno == nulo ) { retornar NotFound(); } retornar Ok(aluno); } // POST: api/Alunos [ HttpPost ] public async Task<ActionResult<Aluno>> CreateAluno(Aluno aluno) { var id = aguarda _dataverseService.CreateStudentAsync(aluno); aluno.Id = id; retornar CreatedAtAction( nome de (GetStudent), novo { id = aluno.Id }, aluno); } // COLOQUE: api/Alunos/{id} [ HttpPut( "{id}" ) ] public async Task<IActionResult> UpdateStudent ( Guid id, Aluno aluno ) { se (id != aluno.Id) { retornar BadRequest(); } aguarde _dataverseService.UpdateStudentAsync(aluno); retornar NoContent(); } // EXCLUIR: api/Alunos/{id} [ HttpDelete( "{id}" ) ] pública assíncrona Task<IActionResult> DeleteStudent ( Guid id ) { aguarde _dataverseService.DeleteStudentAsync(id); retornar NoContent(); } } }

Explicação :

Cada método de ação corresponde a uma operação CRUD.
Injeção de dependência : o controlador usa DataverseService injetado via construtor.

6. Testando a API

Execute o aplicativo

Pressione F5 no Visual Studio para executar o aplicativo. A Swagger UI deve abrir automaticamente.

Usando Swagger UI

Criar um novo aluno

Expanda POST /api/Students .
Clique em Experimentar .
Insira o seguinte JSON no corpo da solicitação :

json

{ "studentName" : "Alice Smith" , "age" : 22 , "e-mail" : "alice.smith@example.com" , "data de inscrição" : "2023-09-01" }
Clique em Executar .
Você deve receber uma resposta 201 Created com os detalhes do aluno.

Recuperar todos os alunos

Expanda GET /api/Students .
Clique em Experimentar e depois em Executar .
A resposta deve listar todos os alunos no Dataverse.

Atualizar um aluno

Copie o Id do aluno que você deseja atualizar.
Expanda PUT /api/Students/{id} .
Clique em Experimentar .
Insira o Id no parâmetro id .
Modifique o JSON no corpo da solicitação conforme necessário.
Clique em Executar .

Excluir um aluno

Expandir DELETE /api/Students/{id} .
Clique em Experimentar .
Digite o Id do aluno a ser excluído.
Clique em Executar .

Verificar no Dataverse

Retorne ao portal do Power Apps.
Abra a tabela Alunos para ver as alterações refletidas.

Conclusão

Você construiu com sucesso uma CRUD Web API usando uma entidade Dataverse na ASP.NET Web API! Esta API pode ser estendida ou integrada a outros aplicativos, fornecendo uma maneira poderosa de gerenciar dados armazenados no Dataverse.

Principais conclusões

Integração do Dataverse : aproveitar o Dataverse permite um gerenciamento de dados escalável e seguro.
Uso do ServiceClient : O Microsoft.PowerPlatform.Dataverse.Client simplifica as interações com o Dataverse.
ASP.NET Web API : Criar APIs com ASP.NET Core é eficiente e está alinhado às práticas modernas de desenvolvimento web.

Próximos passos

Melhorias de segurança : implemente armazenamento seguro para cadeias de conexão e segredos (por exemplo, usando o Azure Key Vault).
Tratamento de erros : adicione mecanismos robustos de tratamento de erros e registro.
Autenticação : Proteja seus endpoints de API com autenticação e autorização.

Recursos adicionais

Procurando otimizar suas habilidades de software? Visite askpedromartins .com para aconselhamento especializado e soluções adaptadas às suas necessidades de desenvolvimento.