Informazioni sul codice DSL

Una soluzione DSL (Domain-Specific Language) genera un'API che è possibile usare per leggere e aggiornare le istanze del linguaggio DSL in Visual Studio. Questa API viene definita nel codice generato dalla definizione DSL. Questo argomento descrive l'API generata.

Soluzione di esempio: Diagrammi componenti

Per creare la soluzione che rappresenta l'origine della maggior parte degli esempi in questo argomento, creare un linguaggio DSL dal modello di soluzione Modelli componenti . Si tratta di uno dei modelli standard visualizzati quando si crea una nuova soluzione DSL.

Premere F5 e sperimentare se non si ha familiarità con questo modello di soluzione. Si noti in particolare che si creano porte trascinando uno strumento porta in un componente e che è possibile connettere le porte.

Struttura della soluzione DSL

Il progetto Dsl definisce l'API per il tuo DSL. Il progetto DslPackage definisce la modalità di integrazione con Visual Studio. È anche possibile aggiungere progetti personalizzati, che possono anche contenere codice generato dal modello.

Directory del codice

La maggior parte del codice in ognuno di questi progetti viene generata da Dsl\DslDefinition.dsl. Il codice generato si trova nella cartella Codice generato . Per visualizzare un file generato, fare clic su [+] accanto al file di generazione .tt.

È consigliabile esaminare il codice generato per comprendere il linguaggio DSL. Per visualizzare i file generati, espandere i file *.tt in Esplora soluzioni.

I file *.tt contengono codice di generazione molto piccolo. Invece, usano direttive <#include> per includere file modello condivisi. I file condivisi sono disponibili in \Programmi\Microsoft Visual Studio 10.0\Common7\IDE\Extensions\Microsoft\DSL SDK\DSL Designer\11.0\TextTemplates

Quando si aggiunge il proprio codice programma alla soluzione DSL, aggiungerlo in un file separato, all'esterno della cartella Codice generato. Potrebbe essere necessario creare una cartella di codice personalizzato . Quando si aggiunge un nuovo file di codice a una cartella personalizzata, ricordarsi di correggere lo spazio dei nomi nello scheletro di codice iniziale.

È consigliabile non modificare direttamente il codice generato, perché le modifiche andranno perse quando si ricompila la soluzione. Invece, per personalizzare il tuo DSL:

• Regolare i molti parametri nella definizione DSL.

• Scrivere classi parziali in file di codice separati, per eseguire l'override dei metodi definiti in o ereditati dalle classi generate. In alcuni casi, è necessario impostare l'opzione Genera doppia derivata di una classe nella definizione DSL per poter eseguire l'override di un metodo generato.

• Imposta le opzioni nella definizione DSL in modo che il codice generato fornisca punti di inserimento per il tuo codice personalizzato.

  Ad esempio, se si imposta l'opzione Has Custom Constructor di una classe di dominio e quindi si compila la soluzione, verranno visualizzati messaggi di errore. Quando si fa doppio clic su uno di questi messaggi di errore, nel codice generato verranno visualizzati commenti che spiegano cosa deve fornire il codice personalizzato.

• Scrivere modelli di testo personalizzati per generare codice specifico per l'applicazione. È possibile usare file di inclusione per condividere parti dei modelli comuni a molti progetti ed è possibile creare modelli di progetto di Visual Studio per configurare progetti inizializzati con la propria struttura di file.

File generati nel linguaggio Dsl

I file generati seguenti vengono visualizzati nel progetto Dsl .

YourDslSchema.xsd

Schema per i file contenenti istanze del DSL. Questo file viene copiato nella directory di compilazione (bin). Quando si installa il DSL, è possibile copiare questo file in \Program Files\Microsoft Visual Studio 11.0\Xml\Schemas in modo che i file modello possano essere convalidati. Per ulteriori informazioni, consultare Distribuzione di soluzioni linguistiche specifiche del dominio.

Se si personalizza la serializzazione impostando le opzioni in Esplora DSL, lo schema cambierà di conseguenza. Tuttavia, se si scrive codice di serializzazione personalizzato, questo file potrebbe non rappresentare più lo schema effettivo. Per altre informazioni, vedere Personalizzazione dell'archiviazione file e della serializzazione XML.

ConnectionBuilders.cs

Un generatore di connessioni è una classe che crea relazioni. Si tratta del code-behind di uno strumento di connessione. Questo file contiene una coppia di classi per ogni strumento di connessione. I nomi sono derivati dai nomi della relazione di dominio e dello strumento di connessione: Generatore relazionie ConnectorToolConnectAction.

Nell'esempio di soluzione del componente, uno dei generatori di connessioni è denominato ConnectionBuilder, si tratta di una coincidenza, perché la relazione di dominio è denominata Connection.

La relazione viene creata nel metodo RelationshipBuilder.Connect() . La versione predefinita verifica che gli elementi del modello di origine e di destinazione siano accettabili e quindi crea un'istanza della relazione. Per esempio:

CommentReferencesSubject(sourceAccepted, targetAccepted);

Ogni classe builder viene generata da un nodo nella sezione Generatori connessioni in Esplora DSL. Un Connect metodo può creare relazioni tra una o più coppie di classi di dominio. Ogni coppia è definita da una direttiva Link Connect, che è possibile trovare in Esplora DSL nel nodo del generatore.

Ad esempio, è possibile aggiungere a un generatore di connessioni direttive Link Connect per ognuno dei tre tipi di relazione nel linguaggio DSL di esempio. In questo modo l'utente dispone di un singolo strumento di connessione. Il tipo di relazione creata dipende dai tipi degli elementi di origine e di destinazione selezionati dall'utente. Per aggiungere le direttive di collegamento Link Connect, fare clic con il pulsante destro del mouse su un builder in Esplora DSL.

Per scrivere codice personalizzato che viene eseguito quando viene creato un tipo specifico di relazione di dominio, selezionare la direttiva Link Connect appropriata nel nodo del generatore. Nella finestra Proprietà impostare Usa connessione personalizzata. Ricompilare la soluzione e quindi specificare il codice per correggere gli errori risultanti.

Per scrivere codice personalizzato eseguito ogni volta che l'utente usa questo strumento di connessione, impostare la proprietà Is Custom del generatore di connessioni. È possibile specificare il codice che stabilisce se è consentito un elemento di origine, se è consentita una combinazione specifica di origine e destinazione e quali aggiornamenti devono essere apportati al modello quando viene stabilita una connessione. Ad esempio, è possibile consentire una connessione solo se non creerebbe un ciclo nel diagramma. Anziché un singolo collegamento di relazione, è possibile instaurare un schema più complesso di elementi interconnessi tra l'origine e la destinazione.

Connectors.cs

Contiene le classi per i connettori, ovvero gli elementi del diagramma che rappresentano in genere relazioni di riferimento. Ogni classe viene generata da un connettore nella definizione DSL. Ogni classe del connettore deriva da BinaryLinkShape

Per rendere il colore e alcune altre caratteristiche di stile in modo variabile durante l'esecuzione, cliccare con il tasto destro sulla classe nel diagramma di definizione DSL e scegliere Aggiungi esposto.

Per rendere variabili le funzionalità di stile aggiuntive in fase di esecuzione, vedere ad esempio TextField e ShapeElement.

Diagram.cs

Contiene la classe che definisce il diagramma. È derivato da Diagram.

Per rendere il colore e altre caratteristiche di stile variabili durante l'esecuzione, fare clic con il pulsante destro del mouse sulla classe nel diagramma di definizione DSL e scegliere Aggiungi esposto.

Inoltre, questo file contiene la FixupDiagram regola, che risponde quando viene aggiunto un nuovo elemento al modello. La regola aggiunge una nuova forma e collega la forma all'elemento del modello.

DirectiveProcessor.cs

Questo processore di direttiva consente agli utenti di scrivere modelli di testo che leggono un'istanza del linguaggio DSL. Il processore di direttiva carica gli assembly (DLL) per il linguaggio DSL e inserisce in modo efficace le using istruzioni per lo spazio dei nomi. In questo modo il codice nei modelli di testo può usare le classi e le relazioni definite nel linguaggio DSL.

Per altre informazioni, vedere Generazione di codice da un linguaggio di Domain-Specific e creazione di processori di direttiva del modello di testo T4 personalizzati.

DomainClasses.cs

Implementazioni delle classi di dominio definite, incluse le classi astratte e la classe radice del modello. Sono derivati da ModelElement.

Ogni classe di dominio contiene:

• Definizione di proprietà e classe del gestore annidata per ogni proprietà di dominio. È possibile eseguire l'override di OnValueChanging() e OnValueChanged(). Per altre informazioni, vedere Gestori delle modifiche dei valori delle proprietà di dominio.

  Nel linguaggio DSL di esempio la Comment classe contiene una proprietà Text e una classe TextPropertyHandlerdel gestore .

• Proprietà della funzione di accesso per le relazioni a cui partecipa questa classe di dominio. Non esiste alcuna classe nidificata per le proprietà del ruolo.

  Nel linguaggio DSL di esempio la Comment classe dispone di funzioni di accesso che accedono al modello padre tramite la relazione ComponentModelHasCommentsdi incorporamento .

• Costruttori. Se si desidera eseguire l'override di questi, impostare Has Custom Constructor nella classe di dominio.

• Metodi del gestore Element Group Prototype (EGP). Questi elementi sono necessari se l'utente può unire (aggiungere) un altro elemento nelle istanze di questa classe. In genere l'utente esegue questa operazione trascinando da un tool per elementi, da un'altra forma o incollando.

  Nel linguaggio DSL di esempio è possibile unire una porta di input o una porta di output a un componente. Inoltre, i componenti e i commenti possono essere uniti al modello. Il valore di

  I metodi del gestore EGP nella classe Component consentono a un componente di accettare porte, ma non commenti. Il gestore EGP nella classe del modello radice accetta commenti e componenti, ma non porte.

  DomainModel.cs

  Classe che rappresenta il modello di dominio. È derivato da DomainModel.

I Chiusure di copia ed eliminazione definiscono quali altri elementi devono essere inclusi quando un elemento viene copiato o eliminato. È possibile controllare questo comportamento impostando le proprietà Propagates Copy and Propagates Delete dei ruoli in ogni lato di ogni relazione. Se si desidera che i valori vengano determinati in modo dinamico, è possibile scrivere codice per eseguire l'override dei metodi delle classi Closing.

DomainModelResx.resx

Contiene stringhe come le descrizioni delle classi di dominio e delle proprietà, i nomi delle proprietà, le etichette della casella degli strumenti, i messaggi di errore standard e altre stringhe che possono essere visualizzate all'utente. Contiene anche icone degli strumenti e immagini per le forme.

Questo file è associato all'assembly compilato e fornisce i valori predefiniti di queste risorse. È possibile localizzare il DSL creando un assembly satellite contenente le risorse localizzate. Tale versione verrà utilizzata quando il linguaggio DSL è installato in una cultura corrispondente alle risorse localizzate. Per ulteriori informazioni, consultare Distribuzione di soluzioni linguistiche specifiche del dominio.

DomainRelationships.cs

Ogni collegamento tra due elementi in un modello è rappresentato da un'istanza di una classe di relazione di dominio. Tutte le classi di relazione sono derivate da ElementLink, che a sua volta è derivato da ModelElement. Poiché si tratta di modelelement, un'istanza di una relazione può avere proprietà e può essere l'origine o la destinazione di una relazione.

HelpKeywordHelper.cs

Fornisce funzioni utilizzate quando l'utente preme F1.

MultiplicityValidation.cs

Nei ruoli di relazione in cui si specifica una molteplicità di 1...1 o 1.*, l'utente deve essere avvisato che è necessaria almeno un'istanza della relazione. Questo file fornisce vincoli di convalida che implementano tali avvisi. Il collegamento 1..1 a un elemento padre di incorporamento non viene verificato.

Affinché questi vincoli vengano eseguiti, è necessario impostare una delle opzioni Uses... nel nodo Editor\Validation in DSL Explorer. Per altre informazioni, vedere Convalida in un linguaggio di Domain-Specific.

PropertiesGrid.cs

Questo file contiene codice solo se è stato associato un descrittore di tipo personalizzato a una proprietà di dominio. Per altre informazioni, vedere Personalizzazione della finestra Proprietà.

SerializationHelper.cs

• Metodo di convalida per assicurarsi che non venga fatto riferimento a due elementi dallo stesso moniker. Per altre informazioni, vedere Personalizzazione dell'archiviazione file e della serializzazione XML.

• Classe SerializationHelper, che fornisce funzioni usate in comune dalle classi di serializzazione.

  Serializer.cs

  Classe serializzatore per ogni classe di dominio, relazione, forma, connettore, diagramma e modello.

  Molte delle funzionalità di queste classi possono essere controllate dalle impostazioni in Esplora DSL in Comportamento di serializzazione XML.

  Shapes.cs

  Una classe per ogni classe di forma nella definizione DSL. Le forme sono derivate da NodeShape. Per altre informazioni, vedere Personalizzazione dell'archiviazione file e della serializzazione XML.

  Per eseguire l'override dei metodi generati con i propri metodi in una classe parziale, impostare Generate Double Derived per il connettore nella definizione DSL. Per sostituire un costruttore con il proprio codice, impostare Has Custom Constructor (Dispone di un costruttore personalizzato).

  Per rendere il colore e altre caratteristiche di stile variabili durante l'esecuzione, fare clic con il pulsante destro del mouse sulla classe nel diagramma di definizione DSL e scegliere Aggiungi esposto.

  Per rendere variabili le funzionalità di stile aggiuntive in fase di esecuzione, vedere ad esempio TextField e ShapeElement

  ToolboxHelper.cs

  Configura la casella degli strumenti installando i prototipi del gruppo di elementi negli strumenti degli elementi. Le copie di questi prototipi vengono unite agli elementi di destinazione quando l'utente esegue lo strumento.

  È possibile eseguire l'override CreateElementPrototype() per definire un elemento della casella degli strumenti che crea un gruppo di diversi oggetti. Ad esempio, è possibile definire un elemento per rappresentare gli oggetti con componenti secondari. Dopo aver modificato il codice, reimpostare l'istanza sperimentale di Visual Studio per cancellare la cache della casella degli strumenti.

File generati nel progetto DslPackage

DslPackage associa il modello DSL alla shell di Visual Studio, gestendo la finestra, la casella degli strumenti e i comandi di menu. La maggior parte delle classi è doppiamente derivate, in modo che sia possibile sovrascrivere qualsiasi dei loro metodi.

CommandSet.cs

Comandi di menu di scelta rapida visibili nel diagramma. È possibile adattare o aggiungere a questo set. Questo file contiene il codice per i comandi. Il percorso dei comandi nei menu è determinato dal file Commands.vsct. Per altre informazioni, vedere Scrittura di comandi utente e azioni.

Constants.cs

GUIDs.

DocData.cs

YourDslDocData gestisce il caricamento e il salvataggio di un modello in un file e crea l'istanza dello Store.

Ad esempio, se si desidera salvare il linguaggio DSL in un database anziché in un file, puoi fare l'override dei metodi Load e Save.

DocView.cs

YourDslDocView gestisce la finestra in cui viene visualizzato il diagramma. Ad esempio, è possibile incorporare il diagramma all'interno di un windows Form:

Aggiungere un file di controllo utente al progetto DslPackage. Aggiungere un pannello in cui è possibile visualizzare il diagramma. Aggiungere pulsanti e altri controlli. Nella visualizzazione codice del modulo, aggiungi il codice seguente, modificando i nomi nel linguaggio DSL:

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Drawing;
using System.Data;
using System.Linq;
using System.Text;
using System.Windows.Forms;
using Microsoft.VisualStudio.Modeling;
using Microsoft.VisualStudio.Modeling.Shell;

namespace Company.EmbedInForm
{
  public partial class UserControl1 : UserControl
  {
    public UserControl1()
    {
      InitializeComponent();
    }

    private DiagramDocView docView;

    public UserControl1(DiagramDocView docView, Control content)
      : this()
    {
      this.docView = docView;
      panel1.Controls.Add(content);
    }

    private void button1_Click(object sender, EventArgs e)
    {
      ExampleModel modelRoot = this.docView.CurrentDiagram.ModelElement as ExampleModel;
      foreach (ExampleElement element in modelRoot.Elements)
      {
       listBox1.Items.Add(element.Name);
      }
    }
  }
  internal partial class EmbedInFormDocView
  {

    private ContainerControl container;

    /// <summary>
    /// Return a User Control instead of the DSL window.
    /// The user control will contain the DSL window.
    /// </summary>

    public override System.Windows.Forms.IWin32Window Window
    {
      get
      {
        if (container == null)
        {
          // Put the normal DSL Window inside our control
          container = new UserControl1(this, (Control)base.Window);
        }
        return container;
      }
    }
  }

}

EditorFactory.cs

Crea un'istanza DocData di e DocView. Soddisfa un'interfaccia standard usata da Visual Studio per aprire un editor all'avvio del pacchetto DSL. Viene fatto riferimento nell'attributo ProvideEditorFactory in Package.cs

GeneratedVSCT.vsct

Individua i comandi di menu standard nei menu, ad esempio il menu di scelta rapida del diagramma, il menu Modifica e così via. Il codice per i comandi si trova in CommandSet.cs. È possibile spostare o modificare i comandi standard ed è possibile aggiungere comandi personalizzati. Per altre informazioni, vedere Scrittura di comandi utente e azioni.

ModelExplorer.cs

Definisci Esploratore Modelli per il linguaggio DSL. Si tratta della visualizzazione albero del modello visualizzata dall'utente insieme al diagramma.

Ad esempio, è possibile eseguire l'override InsertTreeView() per modificare l'ordine in cui gli elementi vengono visualizzati in Esplora modelli.

Se si vuole che la selezione in Esplora modelli continui a essere sincronizzata con la selezione del diagramma, è possibile usare il codice seguente:

protected override void OnSelectionChanged(global::System.EventArgs e)
{
base.OnSelectionChanged(e);
// get the selected element
DslModeling::ModelElement selectedElement =
this.PrimarySelection as DslModeling::ModelElement;
// Select in the model explorer
SelectInModelExplorer<YOURLANGUAGEExplorerToolWindow>(selectedElement);
}
private void SelectInModelExplorer<T>(DslModeling::ModelElement modelElement)
where T : DslShell.ModelExplorerToolWindow
{
DslShell::ModelingPackage package =
this.GetService(typeof(VSShell.Package)) as DslShell::ModelingPackage;

if (package != null)
{
// find the model explorer window
T explorerWindow = package.GetToolWindow(typeof(T), true) as T;
if (explorerWindow != null)
{
// get the tree container
DslShell.ModelExplorerTreeContainer treeContainer =
explorerWindow.TreeContainer;
// find the tree node
DslShell.ExplorerTreeNode treeNode =
treeContainer.FindNodeForElement(modelElement);
// select the node
explorerWindow.TreeContainer.ObjectModelBrowser.SelectedNode = treeNode;
}
}
}

ModelExplorerToolWindow.cs

Definisce la finestra in cui viene visualizzato Esplora modelli. Gestisce la selezione di elementi nell'esploratore.

Package.cs

Questo file definisce la modalità di integrazione del linguaggio DSL in Visual Studio. Gli attributi nella classe del pacchetto registrano il linguaggio DSL come gestore per i file con la tua estensione del file, definiscono la cassetta degli attrezzi e determinano come aprire una nuova finestra. Il metodo Initialize() viene chiamato una volta quando il primo DSL viene caricato in un'istanza di Visual Studio.

Source.extension.vsixmanifest

Per personalizzare questo file, modificare il .tt file.

Questo file controlla la modalità di creazione del pacchetto DSL in un'estensione di integrazione di Visual Studio (VSIX). Per ulteriori informazioni, consultare Distribuzione di soluzioni linguistiche specifiche del dominio.

Contenuti correlati

• Come definire un linguaggio di Domain-Specific
• Informazioni su modelli, classi e relazioni
• Personalizzazione ed estensione di un linguaggio di Domain-Specific
• Scrittura di codice per personalizzare un linguaggio di Domain-Specific