StackSpot.Database.DynamoDB 1.0.1

StackSpot DynamoDB

Componente projetado para padronizar a comunicação com a Amazon DynamoDB para aplicações .NET Core.

Versões suportadas

• net5.0
• net6.0

Uso

1. Adicione o pacote NuGet StackSpot.Database.DynamoDB ao seu projeto.

dotnet add package StackSpot.Database.DynamoDB

2. Configure as variáveis.

• RegionEndpoint - Endpoint regional que será utilizado para requisitar o DynamoDB - Campo Obrigatório.

Você pode sobrescrever a configuração padrão adicionando a seção AddDynamoDb em seu appsettings.json.

  "DynamoDB": {
      "RegionEndpoint": "us-east-1"
  }

3. Adicione ao seu IServiceCollection via services.AddDynamoDb() no Startup da aplicação ou Program tendo como parametro de entrada IConfiguration e IWebHostEnvironment.

services.AddDynamoDB(Configuration);

Implementação

• A classe que será utilizada para o mapeamento da tabela deverá ter a anotação DynamoDBTable, é aqui que definimos o nome da tabela.
• A chave de partição e a chave de classificação(se presente) devem ter, respectivamente, as anotações no nível de propriedade DynamoDBRangeKey e DynamoDBRangeKey.
• Propriedades regulares devem ser marcadas com a anotação DynamoDBProperty, que aceita um parâmetro opcional para especificar um nome para a coluna da tabela distinto do nome da propriedade.

[DynamoDBTable("Test")]
public class Test
{
    //Chave de Partição 
    [DynamoDBHashKey]
    public string Id { get; set; }

    //Chave de Classificação
    [DynamoDBRangeKey]
    public string IdTest { get; set; }    

    [DynamoDBProperty]
    public string Name { get; set; }

    [DynamoDBProperty]
    public string LastName { get; set; }

    [DynamoDBProperty("Emails")]
    public List<string> TestEmails { get; set; }    
}

• SaveAsync - Utilizado para criar ou atualizar a entidade na tabela(Se a entidade existir na tabela, ele atualizada, do contrário ela é criada).

public class TestRepository : ITestRepository
    { 
        private readonly IDynamoDB _dynamoDB;

        public TestRepository(IDynamoDB dynamoDB)
        {
            _dynamoDB = dynamoDB;
        }

        public async Task<Test> AddAsync(Test entity)
        {
            await _dynamoDB.SaveAsync(entity);

            return entity;
        }
    }

• QueryAsync - Utilizado para recuperar uma ou mais entidades. Ele aceita apenas um parâmetro QueryConfig, que é utilizado como filtro.

public class TestRepository : ITestRepository
{ 
    private readonly IDynamoDB _dynamoDB;

    public TestRepository(IDynamoDB dynamoDB)
    {
        _dynamoDB = dynamoDB;
    }

    public async Task<Test> GetByIdAsync(string id, string idTest)
    {
        var queryFilter = new QueryFilter();
        queryFilter.AddCondition("Id", QueryOperator.Equal, id);
        queryFilter.AddCondition("IdTest", QueryOperator.Equal, idTest);

        var queryResult = await _dynamoDB.QueryAsync<Test>(new QueryConfig(queryFilter));

        return queryResult.FirstOrDefault();
    }
}

• LoadAsync - Utilizado para recuperar uma entidade. Existem duas opções, uma utilizando a própria entidade a ser recuperada e outra utilizando a chave de partição e a chave de classificação(caso a tabela tenha).

public class TestRepository : ITestRepository
{ 
    private readonly IDynamoDB _dynamoDB;

    public TestRepository(IDynamoDB dynamoDB)
    {
        _dynamoDB = dynamoDB;
    }

    public async Task<Test> RemoveAsync(Test test)
    {
      await _dynamoDB.LoadAsync(test);
    }

    public async Task<Test> RemoveAsync(string id, string idTest)
    {
      return await _dynamoDB.LoadAsync<Test>(id,idTest);
    }           
}

• DeleteAsync - Utilizado para excluir fisicamente uma entidade. Existem duas opções, uma utilizando a própria entidade a ser excluída e outra utilizando a chave de partição e a chave de classificação(necessário caso a tabela tenha).

public class TestRepository : ITestRepository
{ 
    private readonly IDynamoDB _dynamoDB;

    public TestRepository(IDynamoDB dynamoDB)
    {
        _dynamoDB = dynamoDB;
    }

    public async Task RemoveAsync(Test test)
    {
      await _dynamoDB.DeleteAsync(test);
    }

    public async Task RemoveAsync(string id, string idTest)
    {
      await _dynamoDB.DeleteAsync<Test>(id,idTest);
    }           
}

4. Ambiente local

• Esta etapa não é obrigatória.
• Recomendamos, para o desenvolvimento local, a criação de um contâiner com a imagem do Localstack.
• Para o funcionamento local você deve preencher a variável de ambiente LOCALSTACK_CUSTOM_SERVICE_URL com o valor da url do serviço. O valor padrão do localstack é http://localhost:4566.
• Abaixo um exemplo de arquivo docker-compose com a criação do contâiner:

version: '2.1'

services:
  localstack:
    image: localstack/localstack
    ports:
      - "4566:4566"
    environment:
      - SERVICES=dynamodb
      - AWS_DEFAULT_OUTPUT=json
      - DEFAULT_REGION=us-east-1

Após a criação do contâiner, crie uma tabela para realizar os testes com o componente. Recomendamos que você tenha instalado em sua estação o AWS CLI. Abaixo um exemplo de comando para criação de uma tabela:

aws --endpoint-url=http://localhost:4566 --region=us-east-1 dynamodb create-table --table-name [NOME DA TABELA] --attribute-definitions AttributeName=[NOME DO ATRIBUTO],AttributeType=[TIPO DO ATRIBUTO] --key-schema AttributeName=[NOME DO ATRIBUTO],KeyType=[TIPO DA KEY] --provisioned-throughput ReadCapacityUnits=5,WriteCapacityUnits=5