Implementar classes C# de serialização/desserialização para um novo documento fiscal eletrônico na DLL Unimake.DFe, a partir do nome da subpasta do documento, da pasta de documentação oficial e da pasta explícita de XSDs a implementar, criando uma classe/arquivo de serialização para cada XSD aplicável conforme padrões NFCom/NFe/DCe, INTEROP e testes filtrados do projeto.
Implementar classes C# de serialização/desserialização para um novo documento fiscal eletrônico na DLL Unimake.DFe, a partir do nome da subpasta do documento, da pasta de documentação oficial e da pasta explícita de XSDs a implementar, criando uma classe/arquivo de serialização para cada XSD aplicável conforme padrões NFCom/NFe/DCe, INTEROP e testes filtrados do projeto.
Novo DF-e - Serialização/Desserialização
Objetivo
Implementar classes C# de serialização/desserialização para um novo documento fiscal eletrônico na DLL Unimake.DFe, seguindo a documentação oficial informada pelo usuário e o padrão existente do projeto.
A entrada obrigatória do usuário deve conter:
o nome da subpasta/documento;
o caminho da pasta onde ficam PDFs, manuais, exemplos XML e demais arquivos técnicos da documentação do novo documento;
o caminho da pasta onde ficam os XSDs que devem ser implementados.
Se o nome da subpasta, a pasta de documentação ou a pasta de XSDs não forem informados, solicite somente as informações faltantes antes de alterar arquivos.
Exemplo de uso
Exemplo de mensagem do usuário para acionar a skill:
Use a skill novo-dfe-serializacao.
Documento: NFGas
Documentação: C:\projetos\docs\NFGas
XSDs: C:\projetos\docs\NFGas\Schemas
Princípio central
Não invente um modelo novo. Gere ou ajuste as classes para que os XMLs reais do documento façam round-trip corretamente:
carregar XML de recurso;
desserializar para objeto;
serializar novamente;
comparar o conteúdo gerado com o XML original.
O round-trip não pode ser obtido por serialização genérica. As classes devem modelar explicitamente as tags dos XSDs, como é feito em NFCom.
Regra de ouro: XSD é contrato
Use o XSD como contrato técnico principal da serialização. Exemplos XML, recursos de teste e classes de outros DF-e ajudam a entender o padrão, mas podem estar incompletos, antigos ou inválidos.
Quando houver divergência:
se o XML de exemplo contrariar o XSD, não deforme a classe para aceitar o exemplo inválido;
se uma classe parecida de outro DF-e tiver estrutura diferente, siga o XSD do documento atual;
se um teste existente falhar porque o recurso XML não obedece ao XSD, registre o problema do recurso separadamente e corrija a classe conforme o schema;
não copie campos de protocolos, retornos, eventos ou grupos por analogia sem confirmar a posição exata no XSD.
Antes de implementar
Localize e leia a pasta de documentação informada pelo usuário.
Localize a pasta de XSDs informada pelo usuário.
Faça uma varredura recursiva da pasta de XSDs e inventarie todos os arquivos .xsd existentes nela.
Identifique PDFs, notas técnicas, manuais, exemplos XML, tabelas, leiautes e arquivos auxiliares na pasta de documentação.
Use a documentação informada como fonte principal para tags, grupos, atributos, tipos, cardinalidade, namespaces, versões, regras de assinatura e exemplos.
Localize a pasta do documento em Xml/{Documento} e Unimake.DFe.Test/{Documento}.
Verifique se já existem classes parciais, recursos XML, schemas XSD ou testes do documento.
Procure tipos reaproveitáveis antes de criar novos:
enums em Servicos;
especialmente source/.NET Standard/Unimake.Business.DFe/Servicos/Enums/Enums.cs;
classes comuns em outros Xml/<DFe>;
Signature;
utilitários em Utility.
Para cada tag/propriedade que será implementada, verifique no XSD e na documentação se há domínio fechado de valores, lista de códigos, xs:enumeration, tabela de domínio ou valores predefinidos.
Se a documentação ou a pasta de XSDs estiver incompleta, ilegível, inacessível ou contraditória, pare e peça esclarecimento ou arquivo complementar. Não adivinhe layout fiscal.
Documentação obrigatória
A pasta de documentação é obrigatória e deve orientar a interpretação dos schemas.
Ao analisá-la:
use a pasta de XSDs informada pelo usuário como escopo obrigatório de implementação;
inventarie todos os XSDs da pasta de XSDs antes de implementar;
implemente a serialização/desserialização para todos os XSDs aplicáveis existentes na pasta de XSDs, não somente para o primeiro schema encontrado;
considere também XSDs importados, incluídos ou referenciados por outros XSDs;
prefira schemas XSD e exemplos XML reais para definir a estrutura das classes;
use PDFs, manuais e notas técnicas para confirmar cardinalidade, obrigatoriedade, descrições e regras de negócio;
preserve nomes oficiais de tags, atributos, grupos e namespaces;
identifique versões do leiaute e diferenças entre homologação/produção quando existirem;
não implemente campos ausentes na documentação apenas por analogia com outro DFe;
quando documentação e padrão do projeto divergirem, preserve o padrão técnico do projeto sem violar o leiaute oficial.
Se houver múltiplas versões do leiaute, implemente somente a versão solicitada ou a versão indicada pelos XMLs/schemas da pasta de XSDs. Se não for possível identificar a versão correta, pergunte antes de codificar.
Cobertura obrigatória dos XSDs
A implementação deve cobrir todos os schemas .xsd aplicáveis encontrados na pasta de XSDs informada pelo usuário.
Antes de codificar:
liste recursivamente todos os .xsd da pasta de XSDs informada;
agrupe schemas por mensagem/documento quando houver arquivos principais e arquivos auxiliares;
identifique imports/includes/dependências entre XSDs;
identifique quais schemas representam XMLs de entrada, retorno, processamento, evento, protocolo, consulta, inutilização, distribuição ou outros artefatos do novo DFe;
descarte somente XSD claramente genérico, duplicado, legado ou não aplicável, e registre o motivo no relatório final.
Durante a implementação:
crie uma classe de serialização raiz para cada XSD aplicável que represente um XML principal;
crie um arquivo .cs separado para cada classe raiz, seguindo o padrão de NFCom e NFe (por exemplo, ConsStatServNFCom.cs, RetConsStatServNFCom.cs, NFCom.cs, NFComProc.cs);
não agrupe todas as classes raiz de XSDs diferentes em um único arquivo;
crie classes auxiliares necessárias para grupos complexos reutilizados;
implemente propriedades explícitas para cada tag, grupo, atributo e lista definidos nos XSDs aplicáveis;
siga o estilo de modelagem da pasta source/.NET Standard/Unimake.Business.DFe/Xml/NFCom, em que cada tag relevante vira propriedade tipada com atributo XML adequado;
reaproveite classes existentes quando a semântica for igual;
garanta que cada schema aplicável tenha pelo menos um caminho de serialização/desserialização representado por classe e teste, quando houver XML de exemplo ou for possível criar exemplo confiável a partir da documentação.
Se algum XSD aplicável não puder ser implementado por falta de informação, não ignore silenciosamente. Informe o bloqueio e peça o arquivo, exemplo ou regra faltante.
Extração obrigatória da árvore XSD
Antes de criar ou alterar classes, extraia a estrutura real dos XSDs aplicáveis, seguindo xs:include, xs:import, tipos globais e tipos locais. Prefira análise estruturada do XML/XSD a leitura por aproximação textual.
Monte uma tabela de conferência para cada schema principal:
XSD raiz:
Classe raiz:
Tipo raiz:
Namespace:
Filhos em xs:sequence/xs:choice, na ordem:
Atributos:
Tipos complexos reutilizados:
Tipos simples/enumerations:
Classe/propriedade C# correspondente:
Ao preencher essa tabela, confira obrigatoriamente:
ordem exata de xs:sequence;
alternativas de xs:choice;
minOccurs e maxOccurs;
atributos use="required" e opcionais;
elementos que são grupos diretos versus elementos dentro de subgrupos;
elementos de retorno que pertencem ao protocolo interno, e não ao XML raiz;
elementos de assinatura e conteúdo aberto declarado com xs:any.
Não comece a codificar uma classe raiz enquanto a árvore do XSD correspondente não estiver clara. Essa etapa deve evitar erros como criar wrapper inexistente, achatar grupo aninhado, transformar atributo em elemento ou colocar campo de protocolo no retorno raiz.
Padrões do projeto
Compatibilidade
O projeto principal é netstandard2.0 com LangVersion 7.3.
Não use recursos incompatíveis com C# 7.3 no projeto principal: file-scoped namespace, records, nullable reference types, init-only setters, global usings, collection expressions ou APIs indisponíveis em netstandard2.0.
Testes miram net8.0, mas devem seguir o estilo local e não forçar modernização desnecessária.
Organização
Classes XML ficam em Unimake.Business.DFe.Xml.{Documento}.
Testes ficam em Unimake.DFe.Test.{Documento}.
Cada XSD aplicável que represente XML principal deve ter sua própria classe raiz e seu próprio arquivo .cs.
Arquivos devem seguir o nome da classe/raiz do XML, no padrão já usado por NFCom e NFe.
Não misture serialização com serviço, transporte, configuração ou validação manual, exceto quando for indispensável para compilar ou seguir padrão já existente.
Não altere exemplos, configs, serviços ou schemas fora do necessário para a serialização/testes.
Estrutura das classes XML
Siga o padrão das classes existentes, incluindo:
#pragma warning disable CS1591 quando o arquivo de referência usar;
blocos #if INTEROP no topo;
using System.Runtime.InteropServices dentro de #if INTEROP;
namespace em bloco;
[Serializable()] quando usado em classes equivalentes;
herança de XMLBase nas classes raiz serializáveis;
comentários XML /// <summary> em classes e propriedades públicas, salvo quando o arquivo de referência do mesmo padrão claramente não tiver;
nomes de classes, propriedades e arquivos alinhados ao XML/schema.
uma classe raiz por XSD principal, em arquivo separado, evitando arquivo monolítico com todas as raízes.
propriedades explícitas e tipadas para as tags do XML, no padrão da NFCom; não use propriedades genéricas para esconder a estrutura do schema.
Atributos XML
Use os atributos de serialização conforme o schema:
[XmlRoot] para raiz;
[XmlElement] para elementos;
[XmlAttribute] para atributos;
[XmlText] para conteúdo textual;
[XmlIgnore] para propriedades auxiliares;
[XmlArray]/[XmlArrayItem] somente quando o padrão/schema exigir;
Namespace explícito em elementos como assinatura digital.
Preserve nomes, case, ordem lógica e hierarquia do XML. Não traduza tag fiscal.
Além disso:
propriedades C# devem aparecer na mesma ordem dos filhos em xs:sequence;
atributos do XSD devem ser [XmlAttribute], nunca [XmlElement];
elementos do XSD devem ser [XmlElement], nunca [XmlAttribute];
xs:choice deve ser modelado como alternativas reais, sem criar wrapper inexistente;
grupos aninhados devem permanecer aninhados na classe, sem achatar propriedades para o nível errado;
não invente grupos por analogia com outro documento quando o XSD atual não declarar o grupo.
Proibição de serialização genérica
Não use atalhos genéricos para representar conteúdo que está definido no XSD.
São proibidos como solução para tags conhecidas:
public XmlElement[] Conteudo { get; set; };
[XmlAnyElement];
[XmlAnyAttribute];
object, dynamic ou string contendo XML bruto;
listas genéricas de nós XML para preservar conteúdo sem modelar as tags.
Esses recursos só podem ser usados quando o próprio schema permitir conteúdo aberto/extensível e não houver tags conhecidas a modelar. Nesse caso, justifique no relatório final.
Para cada grupo do XSD, crie classe/propriedades explícitas como no padrão NFCom: propriedades com [XmlElement], [XmlAttribute], listas tipadas, propriedades auxiliares com [XmlIgnore] quando necessário e métodos Add.../Get.../Get...Count para INTEROP quando houver listas.
Propriedades auxiliares
Quando o código usa tipo amigável mas o XML serializa outro formato, use o padrão existente:
propriedade principal com [XmlIgnore];
propriedade ...Field serializável para conversão;
Enum.Parse, cast ou conversor já usado no projeto;
ShouldSerialize...() quando a omissão condicional for necessária e já existir padrão semelhante.
Exemplos típicos:
enum serializado como inteiro;
data/hora serializada em string com formato específico;
decimal com cultura invariável;
chave calculada a partir de dados do documento.
Para campos opcionais (minOccurs="0") com tipo valor, enum ou número:
não serialize valor default como se fosse informado;
use ShouldSerialize...() quando o padrão local permitir omitir o campo com segurança;
use propriedade ...Specified quando o valor default também puder ser válido;
para enum opcional, use sentinela existente do projeto ou ShouldSerialize...() coerente com o domínio;
para inteiro opcional em que 0 não é valor válido, ShouldSerialize...() => Campo > 0 é aceitável quando seguir o padrão local;
strings opcionais podem ser omitidas por null, mas use ShouldSerialize...() se string vazia não deve sair no XML.
Não adicione ShouldSerialize...() em campo obrigatório. A omissão condicional deve refletir o XSD.
Enumeradores obrigatórios
Para cada propriedade/tag implementada, analise se o valor possui domínio fechado.
Crie ou reutilize enum quando houver:
xs:enumeration no XSD;
tipo simples restrito por lista de valores;
tabela de códigos no manual/PDF/nota técnica;
valores predefinidos como ambiente, modelo, emissão, status, tipo de evento, indicador, finalidade, modalidade, UF, município/provedor quando aplicável;
propriedade que no projeto equivalente já usa enum em outro DFe.
Antes de criar enum novo:
procure enum compatível em source/.NET Standard/Unimake.Business.DFe/Servicos/Enums/Enums.cs;
procure também em outros arquivos existentes sob Servicos e Xml;
reutilize enum existente quando a semântica e os valores forem iguais;
não crie enum duplicado com outro nome para o mesmo domínio.
Quando criar enum novo:
coloque no local já usado pelo projeto para enums de DFe, preferencialmente Servicos/Enums/Enums.cs quando o padrão local indicar;
use nomes claros e alinhados ao domínio fiscal;
mantenha valores numéricos/string serializados por propriedade auxiliar quando necessário;
preserve compatibilidade de serialização usando [XmlIgnore] na propriedade enum e uma propriedade ...Field com [XmlElement]/[XmlAttribute] quando o XML exigir número ou string;
documente os membros quando o padrão do arquivo exigir.
Não deixe como int, string ou double uma tag com valores predefinidos se for possível modelar com enum sem quebrar a serialização. Use tipo primitivo apenas quando o valor for realmente aberto, texto livre, número sem domínio fechado ou quando o schema permitir ampla variação.
Listas e INTEROP
Para listas públicas, siga o padrão COM quando a classe equivalente tiver INTEROP:
pesquise por nome de tag/classe equivalente no projeto;
reaproveite enums e tipos já existentes quando a semântica for a mesma;
não duplique tipos comuns apenas mudando o namespace;
crie tipo novo somente quando o schema do novo DFe tiver semântica própria.
Testes unitários
Crie ou ajuste SerializacaoDesserializacaoTest.cs em:
source\Unimake.DFe.Test\{Documento}
Siga o padrão de source\Unimake.DFe.Test\NFCom\SerializacaoDesserializacaoTest.cs.
Cada XML de recurso relevante deve ter teste que:
valida que o arquivo existe;
carrega com XmlDocument;
desserializa usando LerXML<T>() ou XMLUtility.Deserializar<T>(), conforme padrão local;
serializa com GerarXML();
compara InnerText do original com o gerado;
usa [Trait("DFe", "{Documento}")].
Cada XSD aplicável deve ter cobertura por teste de serialização/desserialização quando existir XML de exemplo ou quando for possível montar exemplo confiável a partir da documentação. Não deixe schema aplicável sem teste e sem justificativa.
Inclua recursos XML realistas em Resources somente quando necessário e quando houver material confiável.
Quando um teste de round-trip falhar, valide a causa contra o XSD antes de ajustar a classe:
se a classe serializa fora da ordem, com nível errado, atributo como elemento ou opcional indevido, corrija a classe;
se o recurso XML tiver campos inexistentes no XSD, campos no nível errado ou estrutura antiga, reporte o recurso inválido;
não aceite InnerText igual como prova suficiente se a estrutura XML estiver errada;
quando possível, valide o XML gerado contra o XSD do schema principal.
Execução de testes
Não rode toda a suíte por padrão.
Execute somente os testes criados ou alterados, filtrando por classe, método ou trait do documento. Exemplos:
dotnet test source\Unimake.DFe.Test\Unimake.DFe.Test.csproj --no-restore --filter "FullyQualifiedName~Unimake.DFe.Test.{Documento}.SerializacaoDesserializacaoTest"
dotnet test source\Unimake.DFe.Test\Unimake.DFe.Test.csproj --no-restore --filter "DFe={Documento}"
Rode todos os testes apenas se o usuário solicitar ou se a alteração atingir infraestrutura compartilhada como XMLBase, XMLUtility, Signature, conversores globais ou comportamento comum de serialização.
Se o build falhar por dependência/restauração ausente, informe isso no resultado e não tente baixar pacotes sem aprovação.
Restrições
Não alterar arquivos fora das pastas necessárias, exceto quando indispensável para compilar ou reaproveitar estrutura existente.
Não introduzir novo padrão arquitetural.
Não duplicar tipos já existentes.
Não recriar Signature.
Não alterar padrões globais do projeto.
Não alterar .csproj exceto para incluir recursos ou compilação realmente necessários.
Não atualizar versão de pacote, framework, linguagem ou dependência.
Não executar toda a suíte de testes se for possível executar apenas os testes criados.
Não fazer refatoração ampla junto da implementação.
Não implementar estrutura baseada apenas em suposição quando a documentação oficial não confirmar o leiaute.
Não implementar apenas um XSD quando a pasta de documentação contiver vários schemas aplicáveis.
Não ignorar XSD aplicável sem registrar o motivo no relatório final.
Não colocar todas as classes raiz de XSDs diferentes em um único arquivo.
Não seguir XSDs encontrados fora da pasta de XSDs informada sem confirmação do usuário.
Não criar wrapper, grupo intermediário ou propriedade achatada sem correspondência direta no XSD.
Não transformar atributo do XSD em elemento XML, ou elemento do XSD em atributo XML.
Não serializar campo opcional de tipo valor apenas porque o default do C# existe.
Não mover para o XML raiz campos que pertencem a protocolo, evento interno, infProt, infEvento ou outro grupo aninhado.
Não usar XmlElement[], XmlAnyElement, XmlAnyAttribute, object, dynamic ou XML bruto como substituto de propriedades explícitas para tags conhecidas no XSD.
Não deixar tag com valores predefinidos como string, int ou outro primitivo sem antes verificar e justificar se enum existente ou novo enum deveria ser usado.
Não criar enum novo sem antes pesquisar enum compatível em Enums.cs e nos tipos existentes do projeto.
Checklist antes de finalizar
A entrada {Documento} foi usada para namespace, pasta e testes.
A pasta de documentação informada foi analisada.
A pasta de XSDs informada foi analisada.
Todos os XSDs da pasta de XSDs foram inventariados.
Todos os XSDs aplicáveis foram implementados ou tiveram bloqueio/justificativa registrado.
Includes/imports/tipos globais dos XSDs aplicáveis foram seguidos.
Foi montada conferência de XSD raiz, tipo raiz, filhos, atributos, cardinalidade e classe/propriedade C#.
PDFs/manuais, schemas e exemplos XML relevantes foram considerados quando disponíveis.
Classes seguem os padrões de NFCom, NFe e DFe semelhante.
Cada XSD principal aplicável tem classe raiz e arquivo .cs próprios.
As tags dos XSDs foram modeladas com propriedades explícitas, não com conteúdo XML genérico.
Não há uso de XmlElement[], XmlAnyElement, XmlAnyAttribute, object, dynamic ou XML bruto para tags conhecidas.
A ordem das propriedades segue xs:sequence.
xs:choice foi modelado como alternativas reais.
Atributos do XSD foram implementados com [XmlAttribute].
Grupos aninhados não foram achatados no nível errado.
Campos opcionais de tipo valor/enum/número não serializam default indevido.
Campos de protocolo/retorno/evento foram conferidos no grupo correto do XSD.
Cada propriedade/tag foi analisada para identificar valores predefinidos.
Enums existentes em Enums.cs e no projeto foram reaproveitados quando compatíveis.
Novos enums foram criados para domínios fechados ainda inexistentes.
Tags com domínio fechado não ficaram como primitivo sem justificativa.
Código do projeto principal continua compatível com C# 7.3 e netstandard2.0.
Estrutura reflete fielmente schemas/XMLs de referência.
Atributos XML foram aplicados corretamente.
Namespaces XML oficiais foram preservados.
INTEROP segue o padrão existente.
Propriedades públicas têm summary quando aplicável.
Tipos existentes foram reutilizados quando possível.
Não há duplicação evitável.
Signature.cs foi reutilizada quando aplicável.
Testes foram criados ou ajustados no padrão de serialização/desserialização.
Somente os testes criados/alterados foram executados.
Build/testes executados foram registrados no relatório final.
Saída esperada
Ao finalizar, responda somente com um relatório objetivo:
Documento implementado:
- {Documento}
Pasta de documentação:
- ...
Pasta de XSDs:
- ...
Arquivos criados/modificados:
- ...
Estruturas implementadas:
- ...
Reaproveitamento de código:
- ...
Enums reutilizados/criados:
- ...
XSDs analisados:
- ...
XSDs implementados:
- ...
XSDs não implementados e motivo:
- ...
Testes executados:
- ...
Resultado:
- ...
Não explique passo a passo.
Não inclua introduções.
Não inclua justificativas longas.
Não descreva o processo de execução.
