Personalizando a serialização de XML e armazenamento de arquivos

Artigo
02/25/2013

Quando o usuário salva uma instância, ou modelo, de um idioma específico do domínio (DSL) em Visual Studio, um arquivo XML é criado ou atualizado.O arquivo pode ser recarregado para recriar o modelo no armazenamento.

Você pode personalizar o esquema de serialização, ajustando as configurações em Comportamento de serialização de Xml no Explorer DSL.Existe um nó em Comportamento de serialização de Xml para cada classe de domínio, a propriedade e o relacionamento.As relações estão localizadas em suas classes de origem.Também existem nós que correspondem a forma, conector e classes do diagrama.

Você também pode escrever código de programa para personalização mais avançada.

Observação
Se você deseja salvar o modelo em um determinado formato, mas você não precisará recarregá-lo a partir deste formulário, considere o uso de modelos de texto para gerar a saída do modelo, em vez de um esquema de serialização personalizada.Para obter mais informações, consulte Gerando código a partir de uma linguagem específica de domínio.

Modelo e arquivos de diagrama

Geralmente, cada modelo é salvo em dois arquivos:

O arquivo de modelo tem um nome, como Model1.mydsl.Ele armazena os elementos de modelo e relacionamentos e suas propriedades.A extensão de arquivo como .mydsl é determinado pelo ExtensãoDeArquivo propriedade da Editor nó na definição de DSL.
O arquivo de diagrama tem um nome, como Model1.mydsl.diagram.Ele armazena as formas, conectores e suas posições, cores, espessuras de linha e outros detalhes da aparência do diagrama.Se o usuário exclui um .diagram o arquivo, as informações essenciais no modelo não forem perdidas.Apenas o layout do diagrama é perdido.Quando o arquivo de modelo é aberto, um padrão definido de formas e conectores serão criados.

Para alterar a extensão de arquivo de uma DSL.

Abra a definição de DSL.No Explorer DSL, clique no nó do Editor.
Na janela Properties, edite o ExtensãoDeArquivo propriedade.Não inclua a inicial "." da extensão do nome do arquivo.
No Solution Explorer, altere o nome dos arquivos de modelo de dois item em DslPackage\ProjectItemTemplates.Esses arquivos têm nomes que seguem este formato:

myDsl.diagram

myDsl.myDsl

O esquema de serialização padrão

Para criar um exemplo para este tópico, a seguinte definição de DSL foi usada.

Diagrama de definição de DSL - modelo de árvore genealógica

Essa DSL foi usado para criar um modelo que tenha a seguinte aparência na tela.

Explorer, a caixa de ferramentas e o diagrama de árvore genealógica

Esse modelo foi salvo e, em seguida, reaberto no editor de texto XML:

<?xml version="1.0" encoding="utf-8"?>
<familyTreeModel xmlns:dm0="https://schemas.microsoft.com/VisualStudio/2008/DslTools/Core" dslVersion="1.0.0.0" Id="f817b728-e920-458e-bb99-98edc469d78f" xmlns="https://schemas.microsoft.com/dsltools/FamilyTree">
  <people>
    <person name="Henry VIII" birthYear="1491" deathYear="1547" age="519">
      <children>
        <personMoniker name="/f817b728-e920-458e-bb99-98edc469d78f/Elizabeth I" />
        <personMoniker name="/f817b728-e920-458e-bb99-98edc469d78f/Mary" />
      </children>
    </person>
    <person name="Elizabeth I" birthYear="1533" deathYear="1603" age="477" />
    <person name="Mary" birthYear="1515" deathYear="1558" age="495" />
  </people>
</familyTreeModel>

Observe os seguintes pontos sobre o modelo serializado:

Cada nó XML tem um nome que é o mesmo que um nome de classe de domínio, exceto que a letra inicial fique em minúscula.For example, familyTreeModel and person.
Propriedades de domínio, como nome e BirthYear são serializadas como atributos em nós XML.Novamente, o caractere inicial do nome da propriedade é convertido para minúsculas.
Cada relação é serializada como um nó XML aninhado dentro o fim de origem do relacionamento.O nó possui o mesmo nome, a propriedade da função de origem, mas com um caractere inicial de minúsculas.

Por exemplo, na definição DSL, uma função chamada People for originado na FamilyTree classe.No XML, é representado pelo nó chamado people aninhadas dentro da familyTreeModel nó.
Na extremidade de destino de cada relacionamento de incorporação é serializada como um nó aninhado sob a relação.Por exemplo, o people nó contém vários person nós.
Na extremidade de destino de cada relação de referência é serializada como um identificador de origem, que codifica uma referência para o elemento de destino.

Por exemplo, em um person nó, pode haver uma children relação.Este nó contém identificadores de origem, como:
```
<personMoniker name="/f817b728-e920-458e-bb99-98edc469d78f/Elizabeth I" />
```

Noções básicas sobre identificadores

Identificadores são usados para representar as referências cruzadas entre diferentes partes dos arquivos de modelo e o diagrama.Eles também são usados na .diagram o arquivo para se referir a nós no arquivo do modelo.Há duas formas de identificador de origem:

Os identificadores de ID o GUID do elemento de destino da cotação.Por exemplo:
```
<personShapeMoniker Id="f79734c0-3da1-4d72-9514-848fa9e75157" />
```
Qualificado identificadores de chaves identificar o elemento de destino pelo valor de uma propriedade de domínio designado, chamada de chave moniker.O moniker do elemento de destino é como prefixo o moniker do seu elemento pai na árvore de relacionamentos de incorporação.

Os exemplos a seguir são tirados de uma DSL em que há é uma classe de domínio chamada álbum, que tem um relacionamento de incorporação a um domínio nomeada música de classe:
```
<albumMoniker title="/My Favorites/Jazz after Teatime" />
<songMoniker title="/My Favorites/Jazz after Teatime/Hot tea" />
```
Identificadores de chaves qualificados serão usados se a classe de destino tem uma propriedade de domínio para o qual a opção É o Moniker chave é definida como true na Comportamento de serialização de Xml.No exemplo, essa opção é definida para propriedades de domínio chamadas "Title" nas classes de domínio "Álbum" e "Música".

Qualificado identificadores de chaves são mais fáceis de ler de identificadores de identificação.Se você pretende que o XML de seus arquivos de modelo para ser lido por pessoas, considere o uso de identificadores de chaves qualificados.No entanto, é possível que o usuário defina mais de um elemento para ter a mesma chave de moniker.Chaves duplicadas poderiam causar no arquivo não recarregar corretamente.Portanto, se você definir uma classe de domínio que é referenciada usando identificadores de chaves qualificados, você deve considerar maneiras de impedir que o usuário salvar um arquivo que possui identificadores duplicados.

Para definir uma classe de domínio para ser referenciado por identificadores de ID

Certifique-se de que É o Moniker chave é false para cada propriedade de domínio em que a classe e suas classes base.
1. No Explorer DSL, expanda Data\ de Behavior\Class de serialização de Xml< a classe de domínio >\Element dados.
2. Verifique É o Moniker chave é false para cada propriedade de domínio.
3. Se a classe de domínio tem uma classe base, repita o procedimento nessa classe.
Definir Id serializar = true para a classe de domínio.

Esta propriedade pode ser encontrada em Comportamento de serialização de Xml.

Para definir uma classe de domínio para ser referenciado por identificadores de chaves qualificados

Definir É o Moniker chave para uma propriedade de domínio de uma classe de domínio existente.O tipo da propriedade deve ser string.
1. No Explorer DSL, expanda Data\ de Behavior\Class de serialização de Xml< a classe de domínio >\Element dadose, em seguida, selecione a propriedade de domínio.
2. Na janela Properties, defina É o Moniker chave para true.
- ou -

Criar um novo domínio classe usando o A classe de domínio chamado ferramenta.

Essa ferramenta cria uma nova classe que tem uma propriedade de domínio chamada Name.O É o nome do elemento e É o Moniker chave propriedades desta propriedade de domínio são inicializadas para true.
- ou -

Crie um relacionamento de herança da classe de domínio para outra classe que tem uma propriedade de chave de moniker.

Evitando duplicar identificadores

Se você usar identificadores qualificados de chaves, é possível que dois elementos no modelo de um usuário poderiam ter o mesmo valor na propriedade de chave.Por exemplo, se seu DSL tem uma pessoa que tenha uma propriedade de nome de classe, o usuário pode definir os nomes dos dois elementos para que sejam iguais.Embora o modelo pode ser salvo em arquivo, ele seria não recarregar corretamente.

Há vários métodos que ajudam a evitar essa situação:

Definir É o nome do elemento = true para a propriedade de chave do domínio.Selecione a propriedade de domínio no diagrama de definição de DSL e, em seguida, defina o valor na janela Propriedades.

Quando o usuário cria uma nova instância da classe, esse valor faz com que a propriedade de domínio a ser atribuído automaticamente um valor diferente.O comportamento padrão adiciona um número ao final do nome da classe.Isso não impede que o usuário alterar o nome para uma duplicata, mas ajuda no caso de quando o usuário não define o valor antes de salvar o modelo.
Ative a validação de DSL.No Explorer DSL, selecione Editor\Validation e defina a usa... propriedades para true.

Há um método de validação gerado automaticamente que verifica ambigüidades.O método está na Load categoria de validação.Isso garante que o usuário será avisado que talvez não seja possível reabrir o arquivo.

Para obter mais informações, consulte Validação em um idioma específico do domínio.

Qualificadores e os caminhos de moniker

Um moniker chave qualificado termina com a chave do identificador de origem e é prefixado com o moniker de seu pai na árvore de incorporação.Por exemplo, se o identificador de origem de um álbum é:

<albumMoniker title="/My Favorites/Jazz after Teatime" />

Em seguida, uma das músicas desse álbum poderia ser:

<songMoniker title="/My Favorites/Jazz after Teatime/Hot tea" />

No entanto, se álbuns são referenciados pela identificação em vez disso, em seguida, os identificadores de origem será da seguinte maneira:

<albumMoniker Id="77472c3a-9bf9-4085-976a-d97a4745237c" />
<songMoniker title="/77472c3a-9bf9-4085-976a-d97a4745237c/Hot tea" />

Observe que como um GUID é exclusivo, ele é nunca prefixado pelo identificador de origem de seu pai.

Se você souber que uma propriedade de domínio específico sempre terá um valor exclusivo dentro de um modelo, você pode definir É o Moniker qualificador para true para essa propriedade.Isso fará com que ela seja usada como um qualificador, sem usar o moniker do pai.Por exemplo, se você definir ambos É o Moniker qualificador e É o Moniker chave para a propriedade de domínio do título da classe álbum, nome ou o identificador do modelo não é usada no identificadores de origem para o álbum e seus filhos incorporados:

<albumMoniker name="Jazz after Teatime" />
<songMoniker title="/Jazz after Teatime/Hot tea" />

Personalizando a estrutura do XML

Para fazer as seguintes personalizações, expanda o Comportamento de serialização de Xml o nó no Explorer DSL.Em uma classe de domínio, expanda o nó de elemento de dados para ver a lista de propriedades e relacionamentos que são originados dessa classe.Selecione uma relação e ajuste suas opções na janela Propriedades.

Definir Elemento omitir para true para omitir o nó da função de origem, deixando apenas a lista de elementos de destino.Você não deve definir esta opção se houver mais de um relacionamento entre as classes de origem e de destino.
```
<familyTreeModel ...>
  
  
    <person name="Henry VIII" .../>
    <person name="Elizabeth I" .../>
  
</familyTreeModel>
```

Definir Usar o formulário completo para incorporar os nós de destino em nós que representam as instâncias de relacionamento.Essa opção é definida automaticamente quando você adiciona propriedades do domínio a uma relação de domínio.

<familyTreeModel ...>
  <people>
    <!-- The following node is inserted by using Use Full Form: -->
    <familyTreeModelHasPeople myRelationshipProperty="x1">
      <person name="Henry VIII" .../>
    </familyTreeModelHasPeople>
    <familyTreeModelHasPeople myRelationshipProperty="x2">
      <person name="Elizabeth I" .../>
    </familyTreeModelHasPeople>
  </people>
</familyTreeModel>

Definir representação = elemento ter uma propriedade de domínio, salva como um elemento em vez de como um valor de atributo.
```
<person name="Elizabeth I" birthYear="1533">
  <deathYear>1603</deathYear>
</person>
```
Para alterar a ordem na qual os atributos e relações são serializadas, um item de dados do elemento com o botão direito e use o Mover para cima ou Mover para baixo comandos de menu.

Principal personalização usando o código de programa

Você pode substituir partes ou todo os algoritmos de serialização.

Recomendamos que você estudar o código em Dsl\Generated Code\Serializer.cs e SerializationHelper.cs.

Para personalizar a serialização de uma determinada classe.

Definir Personalizada É no nó da classe em Comportamento de serialização de Xml.
Transformar todos os modelos, criar a solução e para investigar os erros de compilação resultante.Comentários ao lado de cada erro explicam o que o código que você precisa fornecer.

Para fornecer sua próprias serialização para todo o modelo

Substituir os métodos em Dsl\GeneratedCode\SerializationHelper.cs

Opções de comportamento de serialização de Xml

No Explorer DSL, o nó de comportamento de serialização de Xml contém um nó filho para cada classe de domínio, o relacionamento, forma, o conector e a classe de diagrama.Em cada um de nós é uma lista de propriedades e relacionamentos originados no elemento.Relacionamentos são representados por si mesmas e em suas classes de origem.

A tabela a seguir resume as opções que podem ser definidas nesta seção da definição de DSL.Em cada caso, selecione um elemento no Explorer DSL e defina as opções na janela Propriedades.

Dados da classe XML

Esses elementos são encontrados no Explorer DSL em Dados de Behavior\Class de serialização de Xml.

Propriedade	Descrição
Tem o esquema do elemento personalizado	Se for True, indica que a classe de domínio tem um esquema do elemento personalizado
For personalizado	Defina como True se você deseja escrever seu próprio código de serialização e desserialização para esta classe de domínio. Criar a solução e investigue os erros para descobrir as instruções detalhadas.
Classe de domínio	Classe de domínio ao qual se aplica a este nó de dados de classe.Somente leitura.
Element Name	Nome de nó XML para elementos dessa classe.O valor padrão é uma versão em minúscula do nome da classe de domínio.
Nome de atributo do identificador de origem	Nome do atributo usado nos elementos moniker para conter a referência.Se estiver vazio, o nome da propriedade de chave ou id é usado. Neste exemplo, é "name":<personMoniker name="/Mike Nash"/>
Nome do elemento identificador de origem	Nome do elemento xml usado para identificadores se referem a elementos dessa classe. O valor padrão é uma versão em minúsculas do nome da classe sufixado com identificador de "origem".Por exemplo, personMoniker.
Nome do tipo de identificador de origem	Nome do tipo xsd gerado para identificadores para os elementos dessa classe.O XSD é emDsl\Generated Code\*Schema.xsd
Serializar Id	Se verdadeiro, o GUID de elemento estiver incluído no arquivo.Este valor deve ser true se não houver nenhuma propriedade que está marcado como É o Moniker chave e o DSL define relações de referência para esta classe.
Digite um nome	Nome do tipo xml gerado no xsd da classe de domínio designado.
Anotações	Anotações informais associadas a este elemento

Dados de propriedades XML

Nós da propriedade XML são localizadas sob os nós de classe.

Propriedade	Descrição
Propriedade de domínio	Propriedade ao qual se aplica os dados de configuração de serialização de xml.Somente leitura.
É a chave do Moniker	Se verdadeiro, a propriedade é usada como chave para a criação de identificadores que fazem referência a instâncias dessa classe de domínio.
É o Moniker qualificador	Se verdadeiro, a propriedade é usada para criar o qualificador nos identificadores de origem.Se for falso e SerializeId não é válido para esta classe de domínio, os identificadores são qualificados pelo moniker do elemento pai na árvore de incorporação.
Representação	Se o atributo, a propriedade é serializado como um atributo xml; Se o elemento, ele é serializado como um elemento. Se ignorar, não será serializado.
Nome XML	Nome usado para o atributo xml ou o elemento que representa a propriedade.Por padrão, esta é uma versão de minúscula do nome da propriedade de domínio.
Anotações	Anotações informais associadas a este elemento

Dados XML de função

Nós da função de dados encontram-se sob os nós de classe de origem.

Propriedade	Descrição
Tem o Moniker personalizado	Defina como verdadeiro se você desejar fornecer seu próprio código para gerar e resolver identificadores que atravessam esse relacionamento. Para obter instruções detalhadas, compilar a solução e, em seguida, clique duas vezes em mensagens de erro.
Relação de domínio	Especifica a relação aos quais essas opções se aplicam.Somente leitura.
Omitir o elemento	Se verdadeiro, o nó XML que corresponde à função de origem é omitido do esquema. Se houver mais de um relacionamento entre as classes de origem e destino, este nó de função faz distinção entre os links que pertencem a dois relacionamentos.Portanto, recomendamos que você não definir essa opção nesse caso.
Nome do elemento de função	Especifica o nome do elemento XML que é derivado da função de origem.O valor padrão é o nome de propriedade da função.
Use o formulário completo	Se verdadeiro, cada elemento de destino ou o identificador de origem está contido em um nó XML que representa o relacionamento.Isso deve ser definido como verdadeiro se a relação possui suas próprias propriedades de domínio.

Partilhar via