Personalizar mapas de código mediante la edición de los archivos DGML

Artículo
06/19/2023

Para personalizar un mapa de código, puede editar su archivo Directed Graph Markup Language (.dgml). Por ejemplo, puede editar los elementos para especificar estilos personalizados, asignar propiedades y categorías a elementos de código y vínculos, o vincular documentos o direcciones URL a elementos de código o vínculos. Para más información sobre elementos DGML, consulte la referencia de Directed Graph Markup Language (DGML).

Edite el archivo .dgml del mapa de código en un editor XML o de texto. Si el mapa forma parte de la solución de Visual Studio, selecciónelo en el Explorador de soluciones, abra el menú contextual y elija Abrir con, Editor XML (texto).

Nota

Para crear mapas de código, debe tener la edición Visual Studio Enterprise. Cuando se edita el mapa de código en Visual Studio, los atributos y elementos de DGML que no se usan se eliminan al guardar el archivo .dgml. Visual Studio también crea automáticamente elementos de código cuando se agregan nuevos vínculos manualmente. Al guardar el archivo .dgml, los atributos que agregara a un elemento se podrían reorganizar en orden alfabético.

Agrupar elementos de código

Puede agregar nuevos grupos o convertir los nodos existentes en un grupo.

Abra el archivo .dgml en un editor XML o de texto.
Para convertir un elemento de código en un grupo, busque el elemento <Node/> de ese elemento de código.

O bien

Para agregar un grupo nuevo, busque la sección <Nodes>. Agregue un nuevo elemento <Node/>.
En el elemento <Node/>, agregue un atributo Group para especificar si el grupo aparece contraído o expandido. Por ejemplo:
```
<Nodes>
   <Node Id="MyFirstGroup" Group="Expanded" />
   <Node Id="MySecondGroup" Group="Collapsed" />
</Nodes>
```
En la sección <Links>, asegúrese de que existe un elemento <Link/> con los atributos siguientes para cada relación entre un elemento de código de grupo y sus elementos de código secundarios:
- Un atributo Source que especifica el elemento de código de grupo
- Un atributo Target que especifica el elemento de código secundario
- Un atributo Category que especifica una relación Contains entre el elemento de código de grupo y su elemento de código secundario
  
  Por ejemplo:
```
<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 más información sobre el atributo Category, consulte Asignar categorías a elementos de código y vínculos.

Cambio del estilo del mapa

Si desea cambiar el color de fondo y el color de borde del gráfico, edite el archivo .dgml del mapa. Para cambiar el estilo de los elementos de código y los vínculos, consulte Cambiar el estilo de elementos de código y vínculos.

Abra el archivo .dgml en un editor XML o de texto.

En el elemento <DirectedGraph>, agregue cualquiera de los siguientes atributos para cambiar el estilo:

Color de fondo

Background="ColorNameOrHexadecimalValue"

Color del borde

Stroke="StrokeValue"

Por ejemplo:

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

Cambiar el estilo de elementos de código y vínculos

Puede aplicar estilos personalizados a los siguientes elementos de código:

Elementos de código y vínculos únicos
Grupos de elementos de código y vínculos
Grupos de elementos de código y vínculos de acuerdo con ciertas condiciones

Sugerencia

Si tiene estilos que se repiten en varios elementos de código o vínculos, tiene la opción de aplicar una categoría a dichos elementos de código o vínculos y, después, aplicar un estilo a esa categoría. Para más información, consulte Asignar categorías a elementos de código y vínculos y Asignar propiedades a elementos de código y vínculos.

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

Abra el archivo .dgml en un editor XML o de texto.

Busque el elemento <Node/> del elemento de código. Agregue cualquiera de estos atributos para personalizar su estilo:

Color de fondo

Background="ColorNameOrHexadecimalValue"

Esquema

Stroke="ColorNameOrHexadecimalValue"

Grosor del contorno

StrokeThickness="StrokeValue"

Color del texto

Foreground="ColorNameOrHexadecimalValue"

Icono

Icon="IconFilePathLocation"

Tamaño del texto

FontSize="FontSizeValue"

Tipo de texto

FontFamily="FontFamilyName"

Grosor del texto

FontWeight="FontWeightValue"

Estilo del texto

FontStyle="FontStyleName"

Por ejemplo, puede especificar Italic como estilo de texto.

Textura

Style="Glass"

Style="Plain"

Forma

Para reemplazar la forma por un icono, establezca la propiedad Shape en None y establezca la propiedad Icon en la ruta de acceso con el archivo de icono.

Shape="ShapeFilePathLocation"

Por ejemplo:

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

Para aplicar un estilo personalizado a un único vínculo

Abra el archivo .dgml en un editor XML o de texto.
Busque el elemento <Link/> que contiene el nombre del elemento de código de origen y el nombre del elemento de código de destino.

En el elemento <Link/>, agregue cualquiera de los siguientes atributos para personalizar el estilo:

Color de la punta de flecha y el esquema

Stroke="ColorNameOrHexadecimalValue"

Grosor del contorno

StrokeThickness="StrokeValue"

Estilo del contorno

StrokeDashArray="StrokeArrayValues"

Por ejemplo:

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

Para aplicar estilos personalizados a un grupo de elementos de código o vínculos

Abra el archivo .dgml en un editor XML o de texto.
Si no existe ningún elemento <Styles></Styles>, agregue uno bajo el elemento <DirectedGraph></DirectedGraph>, detrás del elemento <Links></Links>.
En el elemento <Styles></Styles>, bajo el elemento <Style/>, especifique los atributos siguientes:
- TargetType="Node | Link | Graph"
- GroupLabel="NameInLegendBox"
- ValueLabel="NameInStylePickerBox"
  
  Para aplicar un estilo personalizado a todos los tipos de destino, no use ninguna condición.

Para aplicar un estilo condicional a los grupos de elementos de código o vínculos

Abra el archivo .dgml en un editor XML o de texto.

En el elemento <Style/>, agregue un elemento <Condition/> que contenga un atributo Expression para especificar una expresión que devuelva un valor booleano.

Por ejemplo:

<Condition Expression="MyCategory"/>

<Condition Expression="MyCategory > 100"/>

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

Esta expresión usa la sintaxis de la forma de Backus-Naur (BNF) siguiente:

<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

Puede especificar varios elementos <Condition/>, que deben ser True para aplicar el estilo.

En la línea que sigue al elemento <Condition/>, agregue uno o varios elementos <Setter/> para especificar un atributo Property y un atributo Value fijo o un atributo Expression calculado para aplicarlo al mapa, a los elementos de código o a los vínculos que satisfacen la condición.

Por ejemplo:
```
<Setter Property="BackGround" Value="Green"/>
```
En este completo y sencillo ejemplo que se mostramos aquí, la condición especifica que un elemento de código debe aparecer en verde o en rojo en función de si su categoría Passed está establecida en True o False:

<?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>

En la tabla siguiente se incluyen algunas condiciones de ejemplo que puede usar:

Establecer el tamaño de fuente como una función del número de líneas de código, lo que también modificará el tamaño del elemento de código. En este ejemplo se usa una única expresión condicional para establecer varias propiedades: FontSize y 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>

Establecer el color de fondo de un elemento de código en función de la propiedad Coverage. Los estilos se evalúan en el orden en que aparecen, al igual que en las instrucciones if-else.

En este ejemplo:

Si Coverage es > 80, la propiedad Background se establece en verde.
En cambio, si Coverage es > 50, la propiedad Background se establece en una sombra naranja en función del valor Coverage de la propiedad .
Por otro lado, la propiedad Background se establece en una sombra roja en función de la propiedad 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>

Establecer la propiedad Shape en None para que el icono reemplace a la sombra. Use la propiedad Icon para especificar la ubicación del icono.

<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>

Asignar propiedades a elementos de código y vínculos

Los elementos de código y los vínculos se pueden organizar asignándoles propiedades. Por ejemplo, puede seleccionar elementos de código que tengan propiedades concretas para que pueda agruparlos, cambiar su estilo u ocultarlos.

Para asignar una propiedad a un elemento de código

Abra el archivo .dgml en un editor XML o de texto.
Busque el elemento <Node/> de ese elemento de código. Especifique el nombre de la propiedad y su valor. Por ejemplo:
```
<Nodes>
   <Node Id="MyNode" MyPropertyName="PropertyValue" />
</Nodes>
```
Agregue un elemento <Property/> a la sección <Properties> para especificar atributos, como el nombre visible y el tipo de datos:
```
<Properties>
   <Property Id="MyPropertyName" Label="My Property" DataType="System.DataType"/>
</Properties>
```

Para asignar una propiedad a un vínculo

Abra el archivo .dgml en un editor XML o de texto.
Busque el elemento <Link/> que contiene el nombre del elemento de código de origen y el nombre del elemento de código de destino.

En el elemento <Node/>, especifique el nombre de la propiedad y su valor. Por ejemplo:

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

Agregue un elemento <Property/> a la sección <Properties> para especificar atributos, como el nombre visible y el tipo de datos:
```
<Properties>
   <Property Id="MyPropertyName" Label="My Property Name" DataType="System.DataType"/>
</Properties>
```

Asignar categorías a elementos de código y vínculos

Las siguientes secciones muestran cómo se pueden organizar los elementos de código mediante categorías y cómo se pueden crear categorías jerárquicas con las que podrá organizar los elementos de código y agregar atributos a categorías secundarias mediante herencia.

Para asignar una categoría a un elemento de código

Abra el archivo .dgml en un editor XML o de texto.
Busque el elemento <Node/> correspondiente al elemento de código que quiera.
En el elemento <Node/>, agregue un atributo Category para especificar el nombre de la categoría. Por ejemplo:
```
<Nodes>
   <Node Id="MyNode" Category="MyCategory" />
</Nodes>
```
Agregue un elemento <Category/> a la sección <Categories> de modo que pueda usar el atributo Label con el fin de especificar el texto visualizado de esa categoría:
```
<Categories>
   <Category Id="MyCategory" Label="My Category" />
</Categories>
```

Para asignar una categoría a un vínculo

Abra el archivo .dgml en un editor XML o de texto.
Busque el elemento <Link/> que contiene el nombre del elemento de código de origen y el nombre del elemento de código de destino.
En el elemento <Link/>, agregue un atributo Category para especificar el nombre de la categoría. Por ejemplo:
```
<Links>
   <Link Source="MyFirstNode" Target="MySecondNode" Category="MyCategory"
</Links>
```
Agregue un elemento <Category/> a la sección <Categories> de modo que pueda usar el atributo Label con el fin de especificar el texto visualizado de esa categoría:
```
<Categories>
   <Category Id="MyCategory" Label="My Category" />
</Categories>
```

Para crear categorías jerárquicas

Abra el archivo .dgml en un editor XML o de texto.

Agregue un elemento <Category/> de la categoría primaria y, a continuación, agregue el atributo BasedOn al elemento <Category/> de la categoría secundaria.

Por ejemplo:

<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>

En este ejemplo, el fondo de MyFirstNode es verde porque su atributo Category hereda el atributo Background de MyParentCategory.

Vincular documentos o direcciones URL a elementos de código y vínculos

Si desea vincular documentos o direcciones URL a elementos de código o vínculos, edite el archivo .dgml del mapa y agregue un atributo Reference al elemento <Node/> —para elementos de código— o el elemento <Link/> —para un vínculo—. Después, puede abrir y ver ese contenido del elemento de código o vínculo. El atributo Reference especifica la ruta de acceso del contenido. Puede tratarse de una ruta de acceso absoluta o de una ruta de acceso relativa a la ubicación del archivo .dgml.

Precaución

Si usa rutas de acceso relativas y el archivo .dgml se mueve a otra ubicación, esas rutas ya no se resolverán. Al intentar abrir y ver el contenido vinculado, se producirá un error que indica que el contenido no se puede ver.

Por ejemplo, puede que quiera vincular estos elementos de código:

Para describir los cambios de una clase, puede vincular la dirección URL de un elemento de código de trabajo, documento u otro archivo .dgml al elemento de código de una clase.
Puede vincular un diagrama de capas a un elemento de código de grupo que representa una capa en la arquitectura lógica del software.
Para mostrar más información sobre un componente que expone una interfaz, puede vincular un diagrama de componentes al elemento de código de esa interfaz.
Vincule un elemento de código a un error o a un elemento de trabajo de Team Foundation Server, o a cualquier otra información relacionada con el elemento de código.

Para vincular un documento o una dirección URL a un elemento de código

Abra el archivo .dgml en un editor XML o de texto.
Busque el elemento <Node/> correspondiente al elemento de código que quiera.
Realice una de las tareas de la tabla siguiente:

Un elemento de código único
- En el elemento <Node/> o <Link/>, agregue un atributo Reference para especificar la ubicación del elemento de código.
  
  Nota
  
  Solo puede tener un atributo Reference por cada elemento.
  
  Por ejemplo:
```
<Nodes>
   <Node Id="MyNode" Reference="MyDocument.txt" />
</Nodes>
<Properties>
   <Property Id="Reference" Label="My Document" DataType="System.String" IsReference="True" />
</Properties>
```
Varios elementos de código
1. En el elemento <Node/> o <Link/>, agregue un nuevo atributo para especificar la ubicación de cada referencia.
2. En la sección <Properties>:
  1. Agregue un elemento <Property/> para cada nuevo tipo de referencia.
  2. Establezca al atributo Id en el nombre del nuevo atributo de referencia.
  3. Agregue el atributo IsReference y establézcalo en True para hacer que la referencia aparezca en el menú contextual Ir a referencia del elemento de código.
  4. Mediante el atributo Label, especifique el texto para mostrar del menú contextual Ir a referencia del elemento de código.
  Por ejemplo:
```
<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>
```
En el mapa, el nombre del elemento de código aparece subrayado. Al abrir el menú contextual del elemento de código o vínculo, aparecerá un menú contextual Ir a referencia que contiene los elementos de código vinculados que puede elegir.

Use el atributo ReferenceTemplate para especificar una cadena común, como una dirección URL, que se use en varias referencias en lugar de repetir esa cadena en la referencia.

El atributo ReferenceTemplate especifica un marcador de posición para el valor de la referencia. En el ejemplo siguiente, el marcador de posición {0} del atributo ReferenceTemplate se reemplazará por los valores de los atributos MyFirstReference y MySecondReference en el elemento <Node/> para generar una ruta de acceso completa:

<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 ver el elemento o elementos de código a los que se hace referencia en el mapa, abra el menú contextual del elemento de código o el vínculo. Elija Ir a referencia y, a continuación, el elemento de código.

Personalizar mapas de código mediante la edición de los archivos DGML

Agrupar elementos de código

Cambio del estilo del mapa

Cambiar el estilo de elementos de código y vínculos

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

Para aplicar un estilo personalizado a un único vínculo

Para aplicar estilos personalizados a un grupo de elementos de código o vínculos

Para aplicar un estilo condicional a los grupos de elementos de código o vínculos

Asignar propiedades a elementos de código y vínculos

Para asignar una propiedad a un elemento de código

Para asignar una propiedad a un vínculo

Asignar categorías a elementos de código y vínculos

Para asignar una categoría a un elemento de código

Para asignar una categoría a un vínculo

Para crear categorías jerárquicas

Vincular documentos o direcciones URL a elementos de código y vínculos

Para vincular un documento o una dirección URL a un elemento de código

Comentarios

Comentarios

Recursos adicionales

Personalizar mapas de código mediante la edición de los archivos DGML

Agrupar elementos de código

Cambio del estilo del mapa

Cambiar el estilo de elementos de código y vínculos

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

Para aplicar un estilo personalizado a un único vínculo

Para aplicar estilos personalizados a un grupo de elementos de código o vínculos

Para aplicar un estilo condicional a los grupos de elementos de código o vínculos

Asignar propiedades a elementos de código y vínculos

Para asignar una propiedad a un elemento de código

Para asignar una propiedad a un vínculo

Asignar categorías a elementos de código y vínculos

Para asignar una categoría a un elemento de código

Para asignar una categoría a un vínculo

Para crear categorías jerárquicas

Vincular documentos o direcciones URL a elementos de código y vínculos

Para vincular un documento o una dirección URL a un elemento de código

Contenido relacionado

Comentarios

Comentarios

Recursos adicionales