Introdução

O objetivo desse manual é dar uma orientação básica sobre como responder à solicitações de atualização no conversor. Eventualmente, estas costumam ser inclusões de novas mensagens, que o mesmo não cobre, ou inconsistências na conversão de mensagens existentes. Ainda não ocorreu uma solicitação que envolva o CORE do conversor, e portanto o mesmo não será coberto nesse manual.

O foco será na manutenção da estrutura das mensagens em si, e nas regras envolvidas para que essas sejam convertidas conforme o esperado.

O projeto utiliza as bibliotecas Newtonsoft e System.Xml.Serialization para realizar a conversão, e ambas exigem annotations em determinadas classes para o seu funcionamento correto.

Arquitetura do Projeto

ConversorDllTester

É um projeto que tem como finalidade simular um client da DLL StandardMessageConversor.

Possui apenas um método MAIN() que lê arquivos XML e JSON do filesystem, e os utiliza como parâmetro para os principiais métodos da DLL.

É utilizado para debug.

StandardMessageConversor

É um projeto do tipo Class Library, que tem uma DLL como artefato gerado pelo build.

Pasta Conversor

Refere-se ao CORE do projeto, onde ocorre o passo a passo para a conversão de fato.

Raramente exige manutenção ou mudanças. Só irá acontecer caso alguma regra na estrutura do JSON de negócio seja alterada.

O importante de destacar aqui é a clase BaseMessageContentClass

Todas as mensagens implementadas no conversor herdam essa classe.

Também é necessário incluir a annotation XmlInclude para cada uma das classes que a herdaram.

Pasta StructureDocumentClass

Agrupa todas as classes referentes à estrutura/modelo dos recursos que estão sendo convertidos.

Pasta Dynamic

Contém as classes geradas para cada uma das mensagens e types existentes, com base nos XSDs da pasta STABLE (TFS).

Refere-se ao CONTEÚDO (Content/BusinessContent/ReturnContent).

Essa pasta é a que fica em constante mudança para novas atualizações, seja alterações ou inclusão de novas classes.

Pasta Static

Contém as classes geradas que serão comuns entre as mensagens.

Quase tudo nela refere-se ao CABEÇALHO (MessageInformation/Header), mas há exceções.

Essa pasta não costuma sofrer atualizações, a não ser que exista mudança de regra.

Importante destacar aqui a classe ReponseStandard. É simplesmente um ListOfInternalId. A regra é: Se não existir uma classe definida para aquela response, o conversor vai utilizar essa como modelo.

A não ser que exista alguma estrutura que fuja desse padrão, o ideal é que de fato essa seja utilizada, para evitar duplicação de código.

Manipulando as estruturas

Disponibilizar apenas a última versão minor

Como regra, não existem breaking changes ao evoluir uma mudança minor. Apenas novos elementos podem ser adicionados, e nenhum pode ser removido.

Portanto, não faz sentido manter a versão 1.001, 1.002 e 1.003. Nesse caso temos apenas a classe referente à versão 1.003.

Gerador de Classes

Ao encontrar a necessidade de que o conversor deva suportar uma nova mensagem, é preciso primeiramente gerar as classes com base no XSD automaticamente, para, posteriormente, decorar alguns elementos com annotations.

Existe um projeto padrão para realizar a conversão. Não entraremos em detalhes nesse manual, mas é basicamente apontar para uma pasta onde está o XSD, e o mesmo irá gerar e salvar arquivos das classes em C#.

Alguns types que ele gerar já podem estar disponíveis na pasta TYPES. Nesse caso, utilize os types que já estão definidos ao invés de substituir.

Se no que foi gerado, existem propriedades que não constam naqueles types, basta adicioná-las na classe existente. 

Sempre se atentar às possíveis annotations que devem ser colocadas.

Annotations

O gerador por padrão não faz todo o trabalho. Aqui entra a parte manual.

É preciso avaliar todas as propriedades geradas para identificar se annotations devem ser criados de acordo com as regras abaixo.

Sem as annotations, a conversão não será realizada conforme o esperado.

Array

Todos os arrays devem conter as annotations XmlArray e XmlArrayItem.

Ignore

Propriedades com valor numérico (final "Field) precisam ter uma propriedade equivalente boolean com o final "Specified". 

Caso contrário, essas propriedades causaram problemas em conversões nas quais as mesmas não estejam presentes no JSON ou XML.

Porém, não queremos que essas propriedades com o final "Specified" apareçam nem no JSON, tão pouco no XML. 
Para evitar esse comportamento, precisamos das annotations XmlIgnore e JsonIgnore.

Atualizando o serviço REST

Para atualizar o serviço REST, que utiliza essa DLL, basta parar o serviço, acessar a pasta do mesmo, e substituir a DLL pela gerada através do build do projeto.