Personalizar mapa de códigos editando os arquivos DGML

Artigo
06/19/2023

Para personalizar um mapa de código, você pode editar seu arquivo Directed Graph Markup Language (.dgml). Por exemplo, você pode editar elementos para especificar estilos personalizados, atribuir propriedades e categorias a elementos de código e links, ou vincular documentos ou URLs a elementos de código ou a links. Para mais informações sobre elementos DGML, consulte a referência Directed Graph Markup Language (DGML).

Edite o arquivo .dgml do mapa de código em um texto ou editor XML. Se o mapa fizer parte da solução do Visual Studio, clique no Gerenciador de Soluções, abra o menu de atalho e escolha Abrir Com, Editor XML (Texto).

Observação

Para criar mapas de código, você deve ter o Visual Studio Enterprise Edition. Quando você edita um mapa de código no Visual Studio, ele limpa todos os elementos e atributos DGML não utilizados excluindo-os quando você salva o arquivo .dgml. Ele também cria elementos de código automaticamente quando você adiciona novos links manualmente. Quando você salva o arquivo .dgml, todos os atributos adicionados a um elemento podem se reorganizar em ordem alfabética.

Elementos de código de grupo

Você pode adicionar novos grupos ou converter nós existentes em um grupo.

Abra o arquivo .dgml em um editor de texto ou XML.
Para converter um elemento de código em um grupo, localize o <Node/> elemento para esse elemento de código.

- ou -

Para adicionar um novo grupo, localize a <Nodes> seção. Adiciona um novo <Node/> elemento.
No elemento <Node/>, adicione um atributo Group para especificar se o grupo aparece expandido ou recolhido. Por exemplo:
```
<Nodes>
   <Node Id="MyFirstGroup" Group="Expanded" />
   <Node Id="MySecondGroup" Group="Collapsed" />
</Nodes>
```
Na seção, <Links>verifique se há um<Link/> elemento com os seguintes atributos para cada relação entre um elemento de código do grupo e seus elementos de código filho:
- Um Source atributo que especifica o elemento de código de grupo
- Um Target atributo que especifica o elemento de código filho
- Um Category atributo que especifica uma Contains relação entre o elemento de código de grupo e seu elemento de código filho
  
  Por exemplo:
```
<Links>
   <Link Category="Contains" Source="MyFirstGroup" Target="FirstGroupChildOne" />
   <Link Category ="Contains" Source="MyFirstGroup" Target="FirstGroupChildTwo" />
   <Link Category ="Contains" Source="MySecondGroup" Target="SecondGroupChildOne" />
   <Link Category="Contains" Source="MySecondGroup" Target="SecondGroupChildTwo" />
</Links>
```
Para mais informações sobre o Category atributo, consulte Atribuir categorias a elementos de código e links.

Alterar o estilo do mapa

É possível alterar a cor do plano de fundo e a cor da borda do mapa editando-se o arquivo .dgml do mapa. Para alterar o estilo de elementos de código e links, consulte Alterar o estilo de elementos de código e links.

Abra o arquivo .dgml em um editor de texto ou XML.

No elemento <DirectedGraph>, adicione todos os seguintes atributos para alterar o estilo:

Cor da tela de fundo

Background="ColorNameOrHexadecimalValue"

Cor da borda

Stroke="StrokeValue"

Por exemplo:

<DirectedGraph Background="Green" xmlns="http://schemas.microsoft.com/vs/2009/dgml" >
   ...
   ...
</DirectedGraph>

Alterar o estilo de elementos de código e links

É possível aplicar estilos personalizados aos seguintes elemento de código:

Links e elementos de código únicos
Grupos de elementos de código e links
Grupos de elementos de código e links com base em determinadas condições

Dica

Se você tiver estilos repetidos em muitos elementos de código ou links, considere aplicar uma categoria a esses elementos de código ou links e, em seguida, aplicar um estilo a essa categoria. Para mais informações, consulte Atribuir categorias a elementos de código e links e Atribuir propriedades a elementos de código e links.

Para aplicar um estilo personalizado a um único elemento de código

Abra o arquivo .dgml em um editor de texto ou XML.

Localize o elemento do elemento de <Node/> código. Adicione qualquer um desses atributos para personalizar seu estilo:

Cor da tela de fundo

Background="ColorNameOrHexadecimalValue"

Estrutura

Stroke="ColorNameOrHexadecimalValue"

Espessura do contorno

StrokeThickness="StrokeValue"

Cor do texto

Foreground="ColorNameOrHexadecimalValue"

ícone

Icon="IconFilePathLocation"

Tamanho do texto

FontSize="FontSizeValue"

Tipo de texto

FontFamily="FontFamilyName"

Peso do texto

FontWeight="FontWeightValue"

Estilo de texto

FontStyle="FontStyleName"

Por exemplo, é possível especificar Italic como o estilo do texto.

Textura

Style="Glass"

-ou-

Style="Plain"

Forma

Para substituir a forma por um ícone, defina a propriedade Shape como None e defina a propriedade Icon como o caminho com o arquivo do ícone.

Shape="ShapeFilePathLocation"

Por exemplo:

<Nodes>
   <Node Id="MyNode" Background="#FF008000" Stroke="#FF000000"
   Foreground="#FFFFFFFF" Icon="...\Icons\Globe.png"/>
</Nodes>

Para aplicar um estilo personalizado a um único link

Abra o arquivo .dgml em um editor de texto ou XML.
Localize o <Link/> elemento que contém os nomes do elemento de código-fonte e do elemento de código de destino.

No elemento <Link/>, adicione todos os seguintes atributos para personalizar o estilo:

Contorno e cor da seta

Stroke="ColorNameOrHexadecimalValue"

Espessura do contorno

StrokeThickness="StrokeValue"

Estilo do contorno

StrokeDashArray="StrokeArrayValues"

Por exemplo:

<Links>
   <Link Source="MyFirstNode" Target="MySecondNode" Background="Green" Stroke="#FF000000" StrokeDashArray="2,2"/>
</Links>

Para aplicar estilos personalizados a um grupo de elementos de código ou links

Abra o arquivo .dgml em um editor de texto ou XML.
Se um elemento <Styles></Styles> não existir, adicione um no elemento <DirectedGraph></DirectedGraph> depois do elemento <Links></Links>.
No elemento <Styles></Styles>, no elemento <Style/> e especifique os seguintes atributos:
- TargetType="Node | Link | Graph"
- GroupLabel=" NameInLegendBox "
- ValueLabel=" NameInStylePickerBox "
  
  Para aplicar um estilo personalizado a todos os tipos de destino, não use uma condição.

Para aplicar um estilo condicional a grupos de elementos de código ou links

Abra o arquivo .dgml em um editor de texto ou XML.

No elemento <Style/>, adicione um elemento <Condition/> que contém um atributo Expression para especificar uma expressão que retorna um valor Booliano.

Por exemplo:

<Condition Expression="MyCategory"/>

-ou-

<Condition Expression="MyCategory > 100"/>

-ou-

<Condition Expression="HasCategory('MyCategory')"/>

Essa expressão usa a seguinte sintaxe BNF (Backus-Naur Form):

<Expression> ::= <BinaryExpression> | \<UnaryExpression> | "("<Expression>")" | <MemberBindings> | <Literal> | \<Number>

<BinaryExpression> ::= <Expression> <Operator> <Expression>

<UnaryExpression> ::= "!" <Expression> | "+" <Expression> | "-" <Expression>

<Operator> ::= "<" | "<=" | "=" | ">=" | ">" | "!=" | "or" | "and" | "+" | "*" | "/" | "-"

<MemberBindings> ::= <MemberBindings> | <MemberBinding> "." <MemberBinding>

<MemberBinding> ::= <MethodCall> | <PropertyGet>

<MethodCall> ::= <Identifier> "(" <MethodArgs> ")"

<PropertyGet> ::= <Identifier>

<MethodArgs> ::= <Expression> | <Expression> "," <MethodArgs> | <empty>

<Identifier> ::= [^. ]*

<Literal> ::= single or double-quoted string literal

<Number> ::= string of digits with optional decimal point

É possível especificar vários <Condition/> elementos, que devem ser verdadeiros para aplicar o estilo.

Na próxima linha depois do <Condition/> elemento, adicione um ou vários <Setter/> elementos para especificar um Property atributo e um atributo Value fixo ou atributo Expression calculado para aplicar ao mapa, aos elemento de código ou aos links que atendam à condição.

Por exemplo:
```
<Setter Property="BackGround" Value="Green"/>
```
Como um exemplo completo simples, a seguinte condição especifica que um elemento de código é exibido em verde ou vermelho com base na possibilidade Passed da categoria estar definida como True ouFalse:

<?xml version="1.0" encoding="utf-8"?>
<DirectedGraph xmlns="http://schemas.microsoft.com/vs/2009/dgml">
   <Nodes>
      <Node Id="MyFirstNode" Passed="True" />
      <Node Id="MySecondNode" Passed="False" />
   </Nodes>
   <Links>
   </Links>
   <Styles>
      <Style TargetType="Node" GroupLabel="Passed" ValueLabel="True">
         <Condition Expression="Passed='True'"/>
         <Setter Property="Background" Value="Green"/>
      </Style>
      <Style TargetType="Node" GroupLabel="Passed" ValueLabel="False">
         <Condition Expression="Passed='False'"/>
         <Setter Property="Background" Value="Red"/>
      </Style>
   </Styles>
</DirectedGraph>

A seguinte tabela inclui algumas condições de exemplo que é possível usar:

Defina o tamanho da fonte como uma função das linhas de código, que também altera o tamanho do elemento de código. Este exemplo usa uma única expressão condicional para definir várias propriedades, FontSize e FontFamily.

<?xml version="1.0" encoding="utf-8"?>
<DirectedGraph xmlns="http://schemas.microsoft.com/vs/2009/dgml">
<Nodes>
   <Node Id="Class1" LinesOfCode ="200" />
   <Node Id="Class2" LinesOfCode ="1000" />
   <Node Id="Class3" LinesOfCode ="20" />
</Nodes>
<Properties>
   <Property Id="LinesOfCode" Label="LinesOfCode" Description="LinesOfCode" DataType="System.Int32" />
</Properties>
<Styles>
   <Style TargetType="Node" GroupLabel="LinesOfCode" ValueLabel="Function">
      <Condition Expression="LinesOfCode > 0" />
      <Setter Property="FontSize" Expression="Math.Max(9,Math.Sqrt(LinesOfCode))" />
      <Setter Property="FontFamily" Value="Papyrus" />
   </Style>
</Styles>
</DirectedGraph>

Defina a cor da tela de fundo de um elemento de código com base na Coverage propriedade. Os estilos são avaliados na ordem em que são exibidos, algo semelhante às instruções if-else.

Neste exemplo:

Se Coverage for > 80, defina a Background propriedade como verde.
Além disso, se Coverage for > 50, defina Background a propriedade como um sombreamento de laranja com base no valor da Coverage propriedade.
Além disso, defina a propriedade Background como um sombreamento com base no valor da propriedade Coverage.

<?xml version="1.0" encoding="utf-8"?>
<DirectedGraph xmlns="http://schemas.microsoft.com/vs/2009/dgml">
<Nodes>
   <Node Id="Class1" Coverage="58" />
   <Node Id="Class2" Coverage="95" />
   <Node Id="Class3" Coverage="32" />
</Nodes>
<Properties>
   <Property Id="Coverage" Label="Coverage" Description="Code coverage as a percentage of blocks" DataType="Double" />
</Properties>
<Styles>
   <Style TargetType="Node" GroupLabel="Coverage" ValueLabel="Good">
      <Condition Expression="Coverage > 80" />
      <Setter Property="Background" Value="Green" />
   </Style>
   <Style TargetType="Node" GroupLabel="Coverage" ValueLabel="OK">
      <Condition Expression="Coverage > 50" />
      <Setter Property="Background" Expression="Color.FromRgb(180 * Math.Max(1, (80 - Coverage) / 30), 180, 0)" />
   </Style>
   <Style TargetType="Node" GroupLabel="Coverage" ValueLabel="Bad">
      <Setter Property="Background" Expression="Color.FromRgb(180, 180 * Coverage / 50, 0)" />
   </Style>
</Styles>
</DirectedGraph>

Defina a propriedade Shape como None de forma que o ícone substitua a forma. Use a propriedade Icon para especificar o local do ícone.

<DirectedGraph xmlns="http://schemas.microsoft.com/vs/2009/dgml">
<Nodes>
   <Node Id="Automation" Category="Test" Label="Automation" />
   <Node Id="C# Provider" Category="Provider" Label="C# Provider" />
</Nodes>
<Categories>
   <Category Id="Provider" Icon="...\Icons\Module.png" Shape="None" />
   <Category Id="Test" Icon="...\Icons\Page.png" Shape="None" />
</Categories>
<Properties>
   <Property Id="Icon" DataType="System.String" />
   <Property Id="Label" Label="Label" Description="Displayable label of an Annotatable object" DataType="System.String" />
   <Property Id="Shape" DataType="System.String" />
</Properties>
<Styles>
   <Style TargetType="Node" GroupLabel="Group" ValueLabel="Has category">
      <Condition Expression="HasCategory('Group')" />
      <Setter Property="Background" Value="#80008080" />
   </Style>
   <Style TargetType="Node">
      <Setter Property="HorizontalAlignment" Value="Center" />
   </Style>
</Styles>
</DirectedGraph>

Atribuir propriedades a elementos de código e links

Você pode organizar elementos de código e links atribuindo propriedades a eles. Por exemplo, é possível selecionar os elementos de código que tenham propriedades específicas de forma que você possa as agrupar, alterar o estilo ou ocultá-los.

Para atribuir uma propriedade a um elemento de código

Abra o arquivo .dgml em um editor de texto ou XML.
Localize o <Node/> elemento para esse elemento de código. Especifique o nome da propriedade e seu valor. Por exemplo:
```
<Nodes>
   <Node Id="MyNode" MyPropertyName="PropertyValue" />
</Nodes>
```
Adicione um elemento <Property/> à seção <Properties> para especificar atributos como seu nome e tipo de dados visíveis:
```
<Properties>
   <Property Id="MyPropertyName" Label="My Property" DataType="System.DataType"/>
</Properties>
```

Para atribuir uma propriedade a um link

Abra o arquivo .dgml em um editor de texto ou XML.
Localize o <Link/> elemento que contém os nomes do elemento de código-fonte e do elemento de código de destino.

No elemento <Node/>, especifique o nome da propriedade e seu valor. Por exemplo:

<Links>
   <Link Source="MyFirstNode" Target="MySecondNode" MyPropertyName="PropertyValue" />
</Links>

Adicione um elemento <Property/> à seção <Properties> para especificar atributos como seu nome e tipo de dados visíveis:
```
<Properties>
   <Property Id="MyPropertyName" Label="My Property Name" DataType="System.DataType"/>
</Properties>
```

Atribua categorias a elementos de código e links

As seções a seguir demonstram como você pode organizar elementos de código atribuindo categorias a eles e como você pode criar categorias hierárquicas que ajudam a organizar elementos de código e adicionar atributos a categorias filho usando herança.

Para atribuir uma categoria a um elemento de código

Abra o arquivo .dgml em um editor de texto ou XML.
Localize o <Node/> elemento para o elemento de código desejado.
No elemento <Node/>, adicione um atributo Category para especificar o nome da categoria. Por exemplo:
```
<Nodes>
   <Node Id="MyNode" Category="MyCategory" />
</Nodes>
```
Adicione um elemento <Category/> à seção <Categories> de forma que seja possível usar o atributo Label para especificar o texto de exibição dessa categoria:
```
<Categories>
   <Category Id="MyCategory" Label="My Category" />
</Categories>
```

Para atribuir uma categoria a um link

Abra o arquivo .dgml em um editor de texto ou XML.
Localize o <Link/> elemento que contém os nomes do elemento de código-fonte e do elemento de código de destino.
No elemento <Link/>, adicione um atributo Category para especificar o nome da categoria. Por exemplo:
```
<Links>
   <Link Source="MyFirstNode" Target="MySecondNode" Category="MyCategory"
</Links>
```
Adicione um elemento <Category/> à seção <Categories> de forma que seja possível usar o atributo Label para especificar o texto de exibição dessa categoria:
```
<Categories>
   <Category Id="MyCategory" Label="My Category" />
</Categories>
```

Para criar categorias hierárquicas

Abra o arquivo .dgml em um editor de texto ou XML.

Adicione um elemento <Category/> da categoria pai e o atributo BasedOn ao elemento <Category/> da categoria filho.

Por exemplo:

<Nodes>
   <Node Id="MyFirstNode" Label="My First Node" Category= "MyCategory" />
   <Node Id="MySecondNode" Label="My Second Node" />
</Nodes>
<Links>
   <Link Source="MyFirstNode" Target="MySecondNode" />
</Links>
<Categories>
   <Category Id="MyCategory" Label="My Category" BasedOn="MyParentCategory"/>
   <Category Id="MyParentCategory" Label="My Parent Category" Background="Green"/>
</Categories>

Neste exemplo, o plano de fundo de MyFirstNode é verde porque seu atributo Category herda o atributo Background de MyParentCategory.

Vincular documentos ou URLs a elementos de código e links

Você pode vincular documentos ou URLs a elementos de código ou a links editando o arquivo .dgml do mapa e adicionando um Reference atributo ao <Node/> elemento para um elemento de código ou o <Link/> elemento para um link. Em seguida, você pode abrir e exibir esse conteúdo do elemento de código ou link. O atributo Reference especifica o caminho desse conteúdo. Ele pode ser um caminho relativo ao local do arquivo .dgml ou um caminho absoluto.

Cuidado

Se você usar caminhos relativos e o arquivo .dgml for movido para um local diferente, esses caminhos não serão mais resolvidos. Quando você tentar abrir e exibir o conteúdo vinculado, um erro indicando que o conteúdo não pode ser exibido será exibido.

Por exemplo, você talvez queira vincular os seguintes elementos de código:

Para descrever as alterações em uma classe, você pode vincular a URL de um elemento de código de trabalho, documento ou outro arquivo .dgml ao elemento de código de uma classe.
Você pode vincular um diagrama de dependência a um elemento de código de grupo que representa uma camada na arquitetura lógica do software.
Para mostrar mais informações sobre um componente que expõe a interface, você talvez queira vincular um diagrama de componente ao elemento de código dessa interface.
Vincule um elemento de código a um item de trabalho ou a um bug do Team Foundation Server, ou qualquer outra informação relacionada ao nó.

Para vincular um documento ou URL a um elemento de código

Abra o arquivo .dgml em um editor de texto ou XML.
Localize o <Node/> elemento para o elemento de código desejado.
Realize uma das tarefas na tabela a seguir:

Um único elemento de código
- No elemento <Node/> ou <Link/>, adicione um Reference atributo para especificar o local do elemento de código.
  
  Observação
  
  Só é possível ter um atributo Reference por elemento.
  
  Por exemplo:
```
<Nodes>
   <Node Id="MyNode" Reference="MyDocument.txt" />
</Nodes>
<Properties>
   <Property Id="Reference" Label="My Document" DataType="System.String" IsReference="True" />
</Properties>
```
Vários elementos de código
1. No elemento <Node/> ou <Link/>, adicione um novo atributo para especificar o local de cada referência.
2. Na seção <Properties>:
  1. Adicione um elemento <Property/> para cada novo tipo de referência.
  2. Defina o atributo Id como o nome do novo atributo de referência.
  3. Adicione o IsReference atributo e defina-o para True fazer a referência aparecer no menu de atalho Ir para Referência do elemento de código.
  4. Use o Label atributo para especificar o texto de exibição no menu de atalho Ir para Referência do elemento de código.
  Por exemplo:
```
<Nodes>
   <Node Id="MyNode" SequenceDiagram="MySequenceDiagram.sequencediagram" ActiveBugs="MyActiveBugs.wiq"/>
</Nodes>
<Properties>
   <Property Id="SequenceDiagram" Label="My Sequence Diagram" DataType="System.String" IsReference="True" />
   <Property Id="ActiveBugs" Label="Active Bugs" DataType="System.String" IsReference="True" />
</Properties>
```
No mapa, o nome do elemento de código aparece sublinhado. Ao abrir o menu de atalho do elemento de código ou do link, você verá um menu de atalho Ir para Referência que contém os elementos de código vinculados a serem escolhidos.

Use o atributo ReferenceTemplate para especificar uma cadeia de caracteres comum, por exemplo, uma URL, usada por várias referências em vez de repetir a cadeia de caracteres na referência.

O atributo ReferenceTemplate especifica um espaço reservado para o valor da referência. No seguinte exemplo, o {0}espaço reservado no ReferenceTemplate atributo será substituído pelos valores MyFirstReference dos MySecondReference atributos no elemento <Node/> para produzir um caminho completo:

<Nodes>
   <Node Id="MyNode" MyFirstReference="MyFirstDocument" MySecondReference="MySecondDocument"/>
   <Node Id="MySecondNode" MyFirstReference="AnotherFirstDocument" MySecondReference="AnotherSecondDocument"/>
</Nodes>
<Properties>
   <Property Id="MyFirstReference" Label="My First Document" DataType="System.String" IsReference="True" ReferenceTemplate="http://www.Fabrikam.com/FirstDocuments/{0}.asp"/>
   <Property Id="MySecondReference" Label="My Second Document" DataType="System.String" IsReference="True" ReferenceTemplate=" http://www.Fabrikam.com/SecondDocuments/{0}.asp"/>
</Properties>

Para exibir o elemento de código referenciado ou os elementos de código do mapa, abra o menu de atalho para o elemento de código ou o link. Escolha Ir para Referência e, em seguida, o elemento de código.

Compartilhar via

Personalizar mapa de códigos editando os arquivos DGML

Elementos de código de grupo

Alterar o estilo do mapa

Alterar o estilo de elementos de código e links

Para aplicar um estilo personalizado a um único elemento de código

Para aplicar um estilo personalizado a um único link

Para aplicar estilos personalizados a um grupo de elementos de código ou links

Para aplicar um estilo condicional a grupos de elementos de código ou links

Atribuir propriedades a elementos de código e links

Para atribuir uma propriedade a um elemento de código

Para atribuir uma propriedade a um link

Atribua categorias a elementos de código e links

Para atribuir uma categoria a um elemento de código

Para atribuir uma categoria a um link

Para criar categorias hierárquicas

Vincular documentos ou URLs a elementos de código e links

Para vincular um documento ou URL a um elemento de código

Comentários

Recursos adicionais

Compartilhar via

Personalizar mapa de códigos editando os arquivos DGML

Elementos de código de grupo

Alterar o estilo do mapa

Alterar o estilo de elementos de código e links

Para aplicar um estilo personalizado a um único elemento de código

Para aplicar um estilo personalizado a um único link

Para aplicar estilos personalizados a um grupo de elementos de código ou links

Para aplicar um estilo condicional a grupos de elementos de código ou links

Atribuir propriedades a elementos de código e links

Para atribuir uma propriedade a um elemento de código

Para atribuir uma propriedade a um link

Atribua categorias a elementos de código e links

Para atribuir uma categoria a um elemento de código

Para atribuir uma categoria a um link

Para criar categorias hierárquicas

Vincular documentos ou URLs a elementos de código e links

Para vincular um documento ou URL a um elemento de código

Conteúdo relacionado

Comentários

Recursos adicionais