Referência DGML

  • Artigo

A DGML (Linguagem de Marcação de Grafo Direcionada) descreve as informações usadas para visualização e para executar a análise de complexidade e é o formato usado para persistir mapas de código no Visual Studio. Ela usa XML simples para descrever gráficos cíclicos e direcionados acíclicos. Um gráfico direcionado é um conjunto de nós conectados por links ou bordas. Nós e links podem ser usados representam estruturas de rede como, por exemplo, elementos em um projeto de software.

Observe que algumas versões do Visual Studio dão suporte apenas a um subconjunto de recursos DGML, consulte Suporte de versão para ferramentas de arquitetura e modelagem.

Observação

Quando você edita um arquivo .dgml, o IntelliSense ajuda você a identificar atributos disponíveis para cada elemento e seus valores. Para especificar a cor em um atributo, use nomes de cores comuns como, por exemplo, "Azul", ou valores hexadecimais ARGB, como "#ffa0b1c3". DGML usa um subconjunto pequeno de formatos de definição de cor do WPF (Windows Presentation Foundation). Para obter mais informações, consulte Classe de Cores.

Sintaxe DGML

A seguinte tabela descreve os tipos de elementos usados em DGML:

  • <DirectedGraph></DirectedGraph>

    Esse elemento é o elemento raiz do documento de mapa de códigos (.dgml). Todos os outros elementos de DGML são exibidos no escopo desse elemento.

    A seguinte lista descreve atributos opcionais que é possível incluir:

    Background - A cor do plano de fundo

    BackgroundImage - O local de um arquivo de imagem a ser usada como o plano de fundo do gráfico.

    GraphDirection - Quando o mapa for definido como o layout da árvore (Sugiyama), organize os nós de forma que a maioria dos links estejam na direção especificada: TopToBottom, BottomToTop, LeftToRight ou RightToLeft. Confira Alterar o layout do mapa.

    Layout - Defina o mapa como os seguintes layouts: None, Sugiyama (layout da árvore), ForceDirected (clusters rápidos) ou DependencyMatrix. Confira Alterar o layout do mapa.

    NeighborhoodDistance - Quando o mapa for definido como o layout da árvore ou o layout de clusters rápidos, mostre apenas os nós que sejam números especificados (1-7) de links afastados de nós selecionados. Confira Alterar o layout do mapa.

    Exemplo:

    <?xml version="1.0" encoding="utf-8"?>
<DirectedGraph Title="DrivingTest" Background="Blue" xmlns="http://schemas.microsoft.com/vs/2009/dgml">
   <Nodes>
      ...
   </Nodes>
   <Links>
      ...
   </Links>
   <Categories>
      ...
   </Categories>
   <Properties>
      ...
   </Properties>
</DirectedGraph>

  • <Nodes></Nodes>

    Esse elemento opcional contém uma lista de elementos <Node/>, que definem nós no mapa. Para obter mais informações, consulte o elemento <Node/>.

    Observação

    Ao fazer referência a um nó indefinido em um elemento <Link/>, o gráfico cria um elemento <Node/> automaticamente.

    Exemplo:

    <?xml version="1.0" encoding="utf-8"?>
<DirectedGraph Title="DrivingTest" xmlns="http://schemas.microsoft.com/vs/2009/dgml">
   <Nodes>
      <Node ... />
   </Nodes>
   <Links>
      <Link ... />
   </Links>
</DirectedGraph>

  • <Node/>

    Esse elemento define um único nó. Ele é exibido na lista de elementos <Nodes><Nodes/>.

    Esse elemento deve incluir os seguintes atributos:

    Id - O nome exclusivo do nó e o valor padrão do atributo Label, caso nenhum atributo Label separado seja especificado. Esse nome deve corresponder ao atributo Source ou Target do link que faz referência a ele.

    A seguinte lista descreve alguns dos atributos opcionais que é possível incluir:

    Label - O nome para exibição do nó.

    Atributos de estilo. Consulte ersonalizar mapa de códigos editando os arquivos DGML.

    Category - O nome de uma categoria que identifica os elementos que compartilham esse atributo. Para obter mais informações, consulte o elemento <Category/>.

    Property - O nome de uma propriedade que identifica elementos que têm o mesmo valor da propriedade. Para obter mais informações, consulte o elemento <Property/>.

    Group - Se o nó contiver outros nós, defina esse atributo como Expanded ou Collapsed para mostrar ou ocultar seu conteúdo. Deve haver um elemento <Link/> que inclua o atributo Category="Contains" e especifique o nó pai como o nó de origem e o nó filho como o nó de destino. Consulte Elementos de código de grupo.

    Visibility - Defina esse atributo como Visible, Hidden ou Collapsed. Usa System.Windows.Visibility. Consulte Ocultar ou mostrar nós e links.

    Reference - Defina esse atributo para vincular a um documento ou a uma URL. Consulte Vincular documentos ou URLs a elementos de código e links.

    Exemplo:

    <?xml version="1.0" encoding="utf-8"?>
<DirectedGraph Title="DrivingTest" xmlns="http://schemas.microsoft.com/vs/2009/dgml">
   <Nodes>
      <Node Id="Driver" Label="Student" Category="Person" />
      <Node Id="Passenger" Label="Instructor" Category="Person" />
      <Node Id="Car" Label="Car" Category="Automobile" />
      <Node Id="Truck" Label="Truck" Category="Automobile" />
   </Nodes>
   <Links>
      <Link ... />
   </Links>
   <Categories>
      <Category Id="Person" Background="Orange" />
      <Category Id="Automobile" Background="Yellow"/>
   </Categories>
</DirectedGraph>

  • <Links></Links>

    Esse elemento contém a lista de elementos <Link>, que definem links entre nós. Para obter mais informações, consulte o elemento <Link/>.

    Exemplo:

    <?xml version="1.0" encoding="utf-8"?>
<DirectedGraph Title="DrivingTest" xmlns="http://schemas.microsoft.com/vs/2009/dgml">
   <Links>
      <Link ... />
   </Links>
</DirectedGraph>

  • <Link/>

    Esse elemento define um único link que conecta um nó de origem a um nó de destino. Ele é exibido na lista de elementos <Links></Links>.

    Observação

    Se esse elemento fizer referência a um nó indefinido, o documento do mapa criará automaticamente um nó com os atributos especificados, se houver.

    Esse elemento deve incluir os seguintes atributos:

    Source - O nó de origem do link

    Target - O nó de destino do link

    A seguinte lista descreve alguns dos atributos opcionais que é possível incluir:

    Label - O nome para exibição do link

    Atributos de estilo. Consulte ersonalizar mapa de códigos editando os arquivos DGML.

    Category - O nome de uma categoria que identifica os elementos que compartilham esse atributo. Para obter mais informações, consulte o elemento <Category/>.

    Property - O nome de uma propriedade que identifica elementos que têm o mesmo valor da propriedade. Para obter mais informações, consulte o elemento <Property/>.

    Exemplo:

    <?xml version="1.0" encoding="utf-8"?>
<DirectedGraph Title="DrivingTest" xmlns="http://schemas.microsoft.com/vs/2009/dgml">
   <Nodes>
      <Node Id="Driver" Label="Student" Category="Person" />
      <Node Id="Passenger" Label="Instructor" Category="Person" />
      <Node Id="Car" Label="Car" Category="Automobile" />
      <Node Id="Truck" Label="Truck" Category="Automobile" />
   </Nodes>
   <Links>
      <Category Id="Person" Background="Orange" />
      <Category Id="Automobile" Background="Yellow"/>
      <Link Source="Driver" Target="Car" Label="Passed" Stroke="Black" Background="Green" Category="PassedTest" />
      <Link Source="Driver" Target="Truck" Label="Failed" Stroke="Black" Background="Red" Category="PassedTest" />
   </Links>
</DirectedGraph>

  • <Categories></Categories>

    Esse elemento contém a lista de elementos <Category/>. Para obter mais informações, consulte o elemento <Category/>.

    Exemplo:

    <?xml version="1.0" encoding="utf-8"?>
<DirectedGraph Title="DrivingTest" xmlns="http://schemas.microsoft.com/vs/2009/dgml">
   <Categories>
       <Category ... />
   </Categories>
</DirectedGraph>

  • <Category/>

    Esse elemento define um atributo Category, que é usado para identificar os elementos que compartilham esse atributo. Um atributo Category pode ser usado para organizar elementos de mapa, fornecer atributos compartilhados por meio da herança ou definir metadados adicionais.

    Esse elemento deve incluir os seguintes atributos:

    Id - O nome exclusivo da categoria e o valor padrão do atributo Label, caso nenhum atributo Label separado seja especificado.

    A seguinte lista descreve alguns dos atributos opcionais que é possível incluir:

    Label - Um nome amigável para o leitor da categoria.

    BasedOn - A categoria pai da qual <Category/> herda o elemento atual.

    No exemplo desse elemento, a categoria FailedTest herda seu atributo Stroke da categoria PassedTest. Confira "Para criar categorias hierárquicas" em Personalizar mapas de código editando os arquivos DGML.

    As categorias também fornecem um comportamento básico de modelo que controla a aparência de nós e links quando exibidos em um mapa. Consulte ersonalizar mapa de códigos editando os arquivos DGML.

    Exemplo:

    <?xml version="1.0" encoding="utf-8"?>
<DirectedGraph Title="DrivingTest" xmlns="http://schemas.microsoft.com/vs/2009/dgml">
   <Nodes>
      <Node Id="Driver" Label="Driver" Category="Person" />
      <Node Id="Car" Label="Car" Category="Automobile" />
      <Node Id="Truck" Label="Truck" Category="Automobile" />
      <Node Id="Passenger" Category="Person" />
   </Nodes>
   <Links>
      <Link Source="Driver" Target="Car" Label="Passed" Category="PassedTest" />
      <Link Source="Driver" Target="Truck" Label="Failed" Category="FailedTest" />
   </Links>
   <Categories>
      <Category Id="Person" Background="Orange" />
      <Category Id="Automobile" Background="Yellow"/>
      <Category Id="PassedTest" Label="Passed" Stroke="Black" Background="Green" />
      <Category Id="FailedTest" Label="Failed" BasedOn="PassedTest" Background="Red" />
   </Categories>
</DirectedGraph>

  • <Properties></Properties>

    Esse elemento contém a lista de elementos <Property/>. Para obter mais informações, consulte o elemento <Property/>.

    Exemplo:

    <?xml version="1.0" encoding="utf-8"?>
<DirectedGraph Title="DrivingTest" xmlns="http://schemas.microsoft.com/vs/2009/dgml">
   <Properties>
       <Property ... />
   </Properties>
</DirectedGraph>

  • <Property/>

    Esse elemento define um atributo Property que é possível usar para atribuir um valor a qualquer elemento ou atributo DGML, inclusive categorias e outras propriedades.

    Esse elemento deve incluir os seguintes atributos:

    • Id - O nome exclusivo da propriedade e o valor padrão do atributo Label, caso nenhum atributo Label separado seja especificado.

    • DataType - O tipo de dados armazenado pela propriedade

      Se você quiser que a propriedade seja exibida na janela Propriedades, use a propriedade Label para especificar o nome para exibição da propriedade.

      Consulte Atribuir categorias a elementos de código e links.

      Exemplo:

    <?xml version="1.0" encoding="utf-8"?>
<DirectedGraph Title="DrivingTest" xmlns="http://schemas.microsoft.com/vs/2009/dgml">
   <Nodes>
      <Node Id="Driver" Label="Driver" Category="Person" DrivingAge="18"/>
      <Node Id="Car" Label="Car" Category="Automobile" />
      <Node Id="Truck" Label="Truck" Category="Automobile" />
      <Node Id="Passenger" Category="Person" />
   </Nodes>
   <Links>
      <Link Source="Driver" Target="Car" Label="Passed" Category="PassedTest" />
      <Link Source="Driver" Target="Truck" Label="Failed" Category="FailedTest" />
   </Links>
   <Categories>
      <Category Id="Person" Background="Orange" />
      <Category Id="Automobile" Background="Yellow"/>
      <Category Id="PassedTest" Label="Passed" Stroke="Black" Background="Green" />
      <Category Id="FailedTest" Label="Failed" BasedOn="PassedTest" Background="Red" />
   </Categories>
   <Properties>
       <Property Id="DrivingAge" Label="Driving Age" DataType="System.Int32" />
   </Properties>
</DirectedGraph>

Aliases para caminhos mais usados

A substituição dos caminhos mais usados por aliases ajuda a reduzir o tamanho do arquivo .dgml e o tempo necessário para carregar ou salvar o arquivo. Para criar um alias, adicione uma seção <Paths></Paths> ao final do arquivo .dgml. Nesta seção, adicione um elemento <Path/> para definir um alias para o caminho:

<Paths>
   <Path Id="MyPathAlias" Value="C:\...\..." />
</Paths>

Para referenciar o alias de um elemento no arquivo .dgml, coloque o Id do elemento <Path/> entre um cifrão ($) e parênteses (()):

<Nodes>
   <Node Id="MyNode" Reference="$(MyPathAlias)MyDocument.txt" />
</Nodes>
<Properties>
   <Property Id="Reference" Label="My Document" DataType="System.String" IsReference="True" />
</Properties>

Confira também