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

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) oferece uma opção de armazenamento seguro e baseado em nuvem para seus dados, atuando como a plataforma de dados subjacente para aplicativos do Microsoft Power Platform e do Dynamics 365.

Neste tutorial, guiaremos você pela criação de uma API Web CRUD (Criar, Ler, Atualizar, Excluir) usando uma entidade do Dataverse na API Web ASP.NET . Este guia passo a passo foi desenvolvido 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

1. Configurando o ambiente de desenvolvimento
2. Criando uma entidade do Dataverse
3. Criando o projeto ASP.NET Web API
4. Conectando-se ao Dataverse a partir da API da Web
5. Implementando Operações CRUD
6. Testando a API
7. 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ê não tiver um ambiente existente.
• Acesse o portal do Power Apps em https://make.powerapps.com/ .

---

2. Criando uma Entidade do Dataverse

Acesse o Dataverse no Power Apps

• Navegue até Dataverse > Tabelas no menu à esquerda.

Criar uma nova tabela (entidade)

1. Clique em + Nova tabela .

2. 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 :

1. Idade

   • Tipo de dados : Número (número inteiro)

2. E-mail

   • Tipo de dados : Texto

3. 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

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

Configurar o Projeto

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

Definir informações adicionais

1. Estrutura : .NET 8.0 (Long-term support)
2. Tipo de autenticação : Nenhum
3. Habilitar suporte OpenAPI : Verificado (para Swagger UI)
4. 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

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

Registrar um aplicativo no Azure AD

1. Acesse o Portal do Azure .

2. Navegue até Azure Active Directory > Registros de aplicativos .

3. Clique em Novo registro .

   • Nome : DataverseWebApiApp
   • Tipos de contas suportados : apenas contas neste diretório organizacional
   • URI de redirecionamento : https://localhost
   • Clique em Registrar .

4. Anote o ID do aplicativo (cliente) .

5. Em Certificados e segredos , 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:

 
{
 "ConnectionStrings": {
 "Dataverse": "AuthType=ClientSecret;Url=https://yourorg.crm.dynamics.com;ClientId=your_client_id;ClientSecret=your_client_secret;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.

Nota 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" :

 
using System;

 namespace DataverseWebApi.Models
 {
 public class Student
 {
 public Guid Id { get; set; }
 public string StudentName { get; set; } 
público int Idade { obter; definir; }
 string pública Email { obter; definir; }
 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 :

 
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
 {
 public class DataverseService
 {
 private readonly ServiceClient _serviceClient;

 public DataverseService(IConfiguration configuration)
 {
 var connectionString = configuration.GetConnectionString("Dataverse");
 _serviceClient = new ServiceClient(connectionString);
 }

 public async Task<Guid> CreateStudentAsync(Student student)
 { 
var entity = new Entity("student"); // Substitua pelo nome lógico da sua entidade
 entity["nome do aluno"] = aluno.NomeDoAluno;
 entity["idade"] = aluno.Idade;
 entity["email"] = aluno.Email;
 entity["data de matrícula"] = aluno.DataDeMatrícula;

 retornar aguardar Task.Run(() => _serviceClient.Create(entidade));
 }

 tarefa pública assíncrona <aluno> GetStudentAsync (ID do guia)
 {
 var colunas = new ColumnSet("nome do aluno", "idade", "e-mail", "data de inscrição");
 var entity = await Task.Run(() => _serviceClient.Retrieve("aluno", id, colunas));

 se (entidade == nulo) retornar nulo;

 retornar novo aluno
 {
 Id = entidade.Id,
 NomeDoAluno = entidade.GetAttributeValue<string>("nome do aluno"),
 Idade = entidade.GetAttributeValue<int>("idade"),
 E-mail = entidade.GetAttributeValue<string>("e-mail"), 
Data de Inscrição = entity.GetAttributeValue<DataHora>("data de inscrição")
 };
 }

 Tarefa pública assíncrona UpdateStudentAsync(Aluno aluno)
 {
 var entidade = nova Entidade("aluno", aluno.Id);
 entity["nome do aluno"] = aluno.NomeDoAluno;
 entity["idade"] = aluno.Idade;
 entity["email"] = aluno.Email;
 entity["data de matrícula"] = aluno.DataDeMatrícula;

 aguardar Task.Run(() => _serviceClient.Update(entidade));
 }

 tarefa pública assíncrona DeleteStudentAsync(Guid id)
 {
 aguardar Task.Run(() => _serviceClient.Delete("aluno", id));
 }

 pública assíncrona Task<List<Student>> 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,
 NomeDoAluno = entidade.GetAttributeValue<string>("nome do aluno"),
 Idade = entidade.GetAttributeValue<int>("idade"),
 E-mail = entidade.GetAttributeValue<string>("e-mail"),
 Data de Inscrição = entity.GetAttributeValue<DataHora>("data de inscrição")
 });
 }

 alunos que retornam;
 }
 }
 }

Explicação :

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

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

Em Program.cs , adicione:

 
builder.Services.AddSingleton<DataverseService>(); 

Crie o StudentsController

Crie um novo controlador StudentsController.cs na pasta Controllers :

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

 namespace DataverseWebApi.Controllers
 {
 [Route("api/[controller]")]
 [ApiController]
 public class StudentsController : ControllerBase
 {
 private readonly DataverseService _dataverseService;

 public StudentsController(DataverseService dataverseService)
 {
 _dataverseService = dataverseService;
 }

 // GET: api/Students
 [HttpGet]
 public async Task<ActionResult<IEnumerable<Student>>> GetStudents()
 {
 var students = await _dataverseService.GetStudentsAsync();
 return Ok(students);
 }

 // GET: api/Students/{id}
 [HttpGet("{id}")] 
pública assíncrona Task<ActionResult<Student>> 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>> CreateStudent(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();
 }

 aguardar _dataverseService.UpdateStudentAsync(aluno);

 retornar NoContent();
 }
 
// EXCLUIR: api/Alunos/{id}
 [HttpDelete("{id}")]
 tarefa pública assíncrona <IActionResult> DeleteStudent (ID do guia)
 {
 aguardar _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 interface do usuário do Swagger deverá abrir automaticamente.

Usando a interface do usuário do Swagger

Criar um novo aluno

1. Expanda POST /api/Students .

2. Clique em Experimentar .

3. Insira o seguinte JSON no corpo da solicitação :

    
   {
    "studentName": "Alice Smith",
    "age": 22,
    "email": "alice.smith@example.com",
    "enrollmentDate": "2023-09-01"
    }
   

4. Clique em Executar .

5. Você deve receber uma resposta 201 Created com os detalhes do aluno.

Recuperar todos os alunos

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

Atualizar um aluno

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

Excluir um aluno

1. Expandir DELETE /api/Students/{id} .
2. Clique em Experimentar .
3. Digite o Id do aluno a ser excluído.
4. 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ê criou com sucesso uma API Web CRUD usando uma entidade do Dataverse na API Web ASP.NET! 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 alinhado às práticas modernas de desenvolvimento web.

Próximos passos

• Aprimoramentos 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 e registro de erros.
• Autenticação : proteja seus endpoints de API com autenticação e autorização.

---

Recursos adicionais

• Documentação do Microsoft Dataverse
• https://github.com/icpmtech/CRUDWebAPIDataverseEntities
• Documentação da API Web do ASP.NET Core
• Pacote NuGet Microsoft.PowerPlatform.Dataverse.Client

---

Quer otimizar suas habilidades em software? Visite askpedromartins.com para obter conselhos de especialistas e soluções personalizadas para suas necessidades de desenvolvimento.