Criando o projeto

Para começarmos a trabalhar temos que criar um projeto com suporte a .NET Core.

Para isso através do Visual Studio vamos criar nosso projeto acessando: File -> New -> Project -> .NET Standard -> Class Library.

Para utilização do provider do Carol, precisamos instalar um pacote chamado Tnf.Provider.Carol disponível em: https://www.myget.org/F/tnf/api/v3/index.json

Podemos agora começar a criar nossa entidade e repositórios para uso do Carol, começando com a definição de nosso módulo:

CarolModule.cs

using Tnf.App.Carol;
using Tnf.App.Carol.Configuration;
using Tnf.Modules;
using Tnf.Architecture.Domain;
using Tnf.Reflection.Extensions;
 
[DependsOn(
	typeof(DomainModule),
    typeof(TnfCarolModule))]
public class CarolModule : TnfModule
{
	public override void PreInitialize()
	{
		Configuration.Modules
			.TnfCarol()
			.Configure(new TnfCarolConfig()
			{
				ApplicationId = "21af0700038211e79daf4a8136534b63",
				TenantId = "8cd6e43115e9416eb23609486fa053e3",
				BaseAddress = "https://totvshealth.carol.ai/api/v1",
				Username = "[email protected]",
				Password = "password"
			});

		base.PreInitialize();
	}
	public override void Initialize()
	{
		IocManager.RegisterAssemblyByConvention(typeof(CarolModule).GetAssembly());
	}
}

Como podemos perceber na definição de nosso módulo, colocamos como dependência através do uso do atributo "DependsOn" o módulo "TnfCarolModule" que fará a configuração de toda a infraestrutura do Carol para uso no assembly criado.

No método PreInitialize estamos configurando através da FluentAPI usando o método TnfCarol, informando as credenciais do serviço, ApplicationId, TenantId, BaseAddress, Username e Password.

Definindo uma entidade

Para definir sua estrutura no Carol é preciso fazer sua especificação na declaração da entidade. Neste exemplo vamos criar uma entidade chamada "President":

PresidentEntity.cs

using Newtonsoft.Json;
using Tnf.App.Carol.Repositories;
 
[JsonObject("president")]
public class PresidentEntity : CarolEntity
{
	public string Name { get; set; }
	public string ZipCode { get; set; }
	public override object GetStagingMapping()
	{
		return new
		{
			name = "string",
			zipCode = "string"
		};
	}
}

Toda entidade do Carol deve herdar da classe CarolEntity fazendo a sobrescrita do método chamado GetStagingMapping, definindo assim a estrutura (nome e tipo do dado) que será persistido dentro do Carol.

No Carol as entidades se tornam registros de Staging em um primeiro momento. Após isso são criados modelos onde esses dados brutos (staging) serão mapeados para DataModels.

Um segundo passo seria a configuração dentro do serviço do Carol para uso de seu MDM (Master Data Management), criando regras de merge, normalização de dados, etc.

O uso do atributo JsonObject provindo do framework Json.NET usado para serialização de entidades descreve o nome da entidade no Carol. Caso a classe que a represente não possua esse atributo, seu nome será usado como referencia.

Consumindo dados

O pacote instalado Tnf.Provider.Carol prove um repositório para utilização do Carol chamado CarolRepositoryBase<Entity>.

Vamos criar um repositório para uso de nossa entidade chamado WhiteHouseRepository:

WhiteHouseRepository.cs

using System.Collections.Generic;
using System.Threading.Tasks;
using Tnf.Domain.Repositories;
using Tnf.Architecture.Dto.WhiteHouse;
using Tnf.App.Dto.Response;
using Tnf.App.Dto.Request;
using Tnf.Architecture.Domain.WhiteHouse;

namespace Tnf.Architecture.Domain.Interfaces.Repositories
{
    public interface IWhiteHouseRepository : IRepository
    {
        Task<ListDto<PresidentDto>> GetAllPresidents(GetAllPresidentsDto request);
        Task<PresidentDto> GetPresidentById(RequestDto<string> requestDto);
        Task<List<string>> InsertPresidentsAsync(List<President> presidents, bool sync = false);
        Task<President> UpdatePresidentsAsync(President president);
        Task<bool> DeletePresidentsAsync(string id);
    }
}

WhiteHouseRepository.cs

using System.Collections.Generic;
using System.Threading.Tasks;
using Tnf.App.Carol.Repositories;
using Tnf.Provider.Carol;
using Tnf.Architecture.Domain.Interfaces.Repositories;
using Tnf.Architecture.Data.Entities;
using Tnf.AutoMapper;
using Tnf.Architecture.Dto.WhiteHouse;
using Tnf.App.Dto.Response;
using Tnf.App.Dto.Request;
using Tnf.Architecture.Domain.WhiteHouse;
using System.Linq;

namespace Tnf.Architecture.Data.Repositories
{
    public class WhiteHouseRepository : CarolRepositoryBase<PresidentPoco>, IWhiteHouseRepository
    {
        public WhiteHouseRepository(ICarolClient client) :
            base(client)
        {
        }

        public async Task<bool> DeletePresidentsAsync(string id)
        {
            return await DeleteAsync(id);
        }

        public async Task<ListDto<PresidentDto>> GetAllPresidents(GetAllPresidentsDto request)
        {
            var response = new ListDto<PresidentDto>();

            var query = Client.Queries<PresidentPoco>().ProcessFilter()
                .SkipAndTakeByRequestDto(request)
                .OrderByRequestDto(request)
                .IndexType(Provider.Carol.Messages.ProcessFilter.IndexType.STAGING)
                .MustList((m) => m.TypeFilter()
                                  .MatchFilter(p => p.Name, request.Name)
                                  .TermFilter(p => p.Address.ZipCode.Number, request.ZipCode));

            var resultData = await GetAllAsync(query);

            response.Total = resultData.TotalHits;
            response.Items = resultData.Hits.MapTo<List<PresidentDto>>();
            response.HasNext = resultData.TotalHits > ((request.Page - 1) * request.PageSize) + response.Items.Count();

            return response;
        }

        public async Task<PresidentDto> GetPresidentById(RequestDto<string> requestDto)
        {
            var presidentData = await GetAsync(requestDto.GetId());
            var president = presidentData.MapTo<PresidentDto>();

            return president;
        }

        public async Task<List<string>> InsertPresidentsAsync(List<President> presidents, bool sync = false)
        {
            var pocos = presidents.MapTo<List<PresidentPoco>>();
            var result = await InsertAsync(pocos, sync);

            return result.Select(p => p.Id).ToList();
        }

        public async Task<President> UpdatePresidentsAsync(President president)
        {
            var poco = president.MapTo<PresidentPoco>();
            var result = await UpdateAsync(poco);

            return president;
        }
    }
}

Quando definimos nosso repositório recebemos como parâmetro uma interface chamada ICarolClient. Esse tipo é injetado via dependência representando o client de conexão com o Carol.

Através dele será possível criar consultas mais complexas ou acessar funcionalidades expostas dentro do provider do Carol.

Para criar uma consulta por exemplo note que o método GetAll de nosso repositório realiza a construção da query através do objeto ICarolClient usando a função: Client.Queries<PresidentEntity>().ProcessFilter()

Esse método retorna uma interface através de uma API fluente onde é possível construir a consulta desejada. O método GetAllAsync do CarolRepositoryBase recebe o resultado dessa query criada pelo Client.Queries<PresidentEntity>().ProcessFilter() retornando assim os registros que satisfazerem a sentença.

Essa API exposta e seu uso pode ser consultado através da documentação do Carol em http://docs.carol.ai/5-querying-data/

Note que no método InsertAsync do repositório recebe um parâmetro informando se a operação é síncrona ou assíncrona: A diferença entre as operações se da no modo como os dados são persistidos no Carol. A operação síncrona cria registro por registro na sequência e espera o seu processamento pela interface de MDM (Master Data Management) do Carol retornando após o dado passar por todo o processo.

Quando a operação é assíncrona os dados são inseridos em lote não esperando o seu processamento pelo MDM. Um processo posteriormente irá processar os registros pendentes no Carol.

Árvore de páginas

Carol

Criando o projeto

Definindo uma entidade

Consumindo dados