了解 DSL 程式碼

發行項
03/24/2017

如需 Visual Studio 2017 的最新文件請參閱 Visual Studio 2017 文件。

網域指定的語言 (DSL) 方案會產生可用來讀取及更新 Visual Studio 中之 DSL 執行個體的應用程式開發介面。這個 API 是從 DSL 定義產生的程式碼中定義。本主題說明產生的 API。

範例方案︰元件圖表

若要建立方案，大部分的範例，本主題中的來源，建立從 DSL 元件模型 方案範本。這是當您建立新的 DSL 方案時所顯示的標準範本。

注意

元件圖表 DSL 範本與 UML 元件圖表，您可以使用 Visual Studio 中的 [架構] 功能表建立不相關。在 新的專案 對話方塊方塊中，展開 其他專案類型 \ 擴充性 然後按一下 [ 定義域專屬語言設計工具。

按 f5 鍵進行實驗中，如果您不熟悉這個方案範本。特別注意到您的連接埠工具拖曳到元件，請建立連接埠，而且您可以連接的連接埠。

元件和相互連接的通訊埠

DSL 方案的結構

Dsl 專案定義 DSL 的 API。 DslPackage 專案可讓您定義如何與整合 Visual Studio。您也可以加入自己的專案，也可以包含從模型產生的程式碼。

程式碼目錄

大部分的每個專案中的程式碼會產生從 Dsl\DslDefinition.dsl。產生的程式碼位於 產生的程式碼 資料夾。若要查看產生的檔案，請按一下 [ [+] 旁邊產生 .tt 檔案。

我們建議您檢查產生的程式碼，可協助您了解 DSL。若要查看產生的檔案，展開 [方案總管] 中的 *.tt 檔案。

*.Tt 檔案包含極少的產生程式碼。相反地，這些檔案使用 <#include> 指示詞來包含共用範本檔案。共用的檔案位於 files\microsoft Visual Studio 10.0\Common7\IDE\Extensions\Microsoft\DSL \ common7\ide\extensions\microsoft\dsl SDK\DSL Designer\11.0\TextTemplates

當您將您自己的程式碼加入 DSL 方案時，將它加入不同的檔案，產生的程式碼] 資料夾之外。您可能想要建立 的自訂程式碼 資料夾。（當您將新的程式碼檔案加入自訂資料夾時，請記得修正初始程式碼基本架構中的命名空間。）

我們強烈建議您不執行，直接編輯產生的程式碼因為重建方案後，您的編輯將會遺失。相反地，若要自訂您的 DSL:

調整 DSL 定義中的許多參數。
撰寫不同的程式碼檔案中的部分類別，來覆寫方法中，定義或所產生的類別繼承。在某些情況下，您必須設定 產生雙衍生 在 DSL 定義中，類別的選項，才能覆寫產生的方法。
在 DSL 定義中，讓您的程式碼提供「攔截」產生的程式碼中設定選項。

例如，如果您設定 有自訂建構函式 網域類別的選項，然後建置方案，您會看到錯誤訊息。當您按兩下其中一個錯誤訊息時，您會看到說明應提供的自訂程式碼中產生的程式碼註解。
撰寫文字範本產生的應用程式特定的程式碼。您可以使用包含檔案，以共用許多專案通用的範本組件，也可以建立 Visual Studio 專案範本，以設定透過您自己的檔案結構初始化的專案。

在 Dsl 中產生的檔案

下列產生的檔案會出現在 Dsl 專案。

您的 Dsl Schema.xsd

結構描述檔案包含您的 DSL 執行個體。這個檔案複製到編譯 (bin) 目錄。當您安裝 DSL 時，您可以複製此檔案來 files\microsoft Visual Studio 11.0\Xml\Schemas 以驗證模型檔。如需詳細資訊，請參閱部署網域指定的語言方案。

如果您設定來自訂序列化選項 DSL 總管] 中，結構描述會隨之變更。不過，如果您撰寫您自己的序列化程式碼，這個檔案可能不再表示實際的結構描述。如需詳細資訊，請參閱自訂檔案儲存體和 XML 序列化。

ConnectionBuilders.cs

連接產生器是建立關聯性的類別。它是連接工具背後的程式碼。這個檔案包含一對每個連接工具的類別。其名稱衍生自網域關聯性和連接工具的名稱︰ 關聯性產生器中，和 連接工具ConnectAction。

（在元件方案範例中，一個連接產生器稱為 ConnectionBuilder，這是巧合，因為網域關聯性名為連線）。

在建立關聯性 關聯性Builder.Connect() 方法。預設版本驗證來源和目標模型項目是可接受的則會具現化關聯性。例如：

CommentReferencesSubject(sourceAccepted, targetAccepted);

每個產生器會產生類別中的節點從 連接產生器 DSL 總管] 中的區段。一個 Connect 方法可建立一組或多組網域類別之間的關聯性。每一組是由 Link Connect 指示詞，您可以產生器節點下找到 DSL 總管] 中定義。

比方說，您可以加入一個連接產生器 Link Connect 指示詞的三種類型的範例 DSL 中的關聯性。這會提供使用者一個連接工具。具現化的關聯性類型取決於使用者所選取的來源和目標項目類型。若要加入 Link Connect 指示詞，以滑鼠右鍵按一下 DSL 總管] 中的產生器。

若要撰寫自訂程式碼執行建立特定類型的網域關聯性時，選取適當 Link Connect 指示詞產生器節點下。在 [屬性] 視窗中，設定 使用自訂連接。重建方案，然後提供 [程式碼以修正產生的錯誤。

撰寫自訂的使用者使用這個連接工具時執行的程式碼，請設定 是自訂 連接產生器的屬性。您可以提供程式碼，決定是否允許來源項目，來源的特定組合是否允許目標，以及更新模型時應進行連線。例如，您可以在它不會在圖表中建立迴圈時，才允許連線。而不是單一關聯性連結，您可以具現化來源和目標之間伺服器內部相關項目更複雜的模式。

Connectors.cs

包含連接器，也就是通常表示參考關聯性的圖表項目類別。每個類別會產生從 DSL 定義中的一個連接器。每一個連接線類別衍生自 BinaryLinkShape

若要將執行階段的色彩和其他一些樣式功能變數，以滑鼠右鍵按一下 DSL 定義圖上的類別，並指向 加入已公開。

若要將其他樣式功能變數在執行階段，請參閱例如 TextField 和 ShapeElement。

Diagram.cs

包含定義圖表的類別。它衍生自圖表。

若要將執行階段的色彩和其他一些樣式功能變數，以滑鼠右鍵按一下 DSL 定義圖上的類別，並指向 加入已公開。

此外，這個檔案包含 FixupDiagram 規則，會在新項目加入至模型時回應。此規則會加入新圖形，並將圖形連結至模型項目。

DirectiveProcessor.cs

這個指示詞處理器可協助您撰寫文字範本，以讀取您的 DSL 執行個體的使用者。這個指示詞處理器會載入 DSL 的組件 (DLL)，並有效地插入命名空間的 using 陳述式。這可以讓程式碼的文字範本，若要使用的類別和您在 DSL 中定義的關聯性。

如需詳細資訊，請參閱定義域專屬語言產生程式碼和建立自訂 T4 文字範本指示詞處理器。

DomainClasses.cs

您已經定義，包括抽象類別和模型根類別中的網域類別的實作。衍生自 ModelElement。

每個網域類別包含︰

屬性定義和巢狀處理常式類別的每個網域屬性。您可以覆寫 onvaluechanging （）和 onvaluechanged （）。如需詳細資訊，請參閱網域屬性值變更處理常式。

在範例 DSL 中，Comment 類別包含 Text 屬性和 TextPropertyHandler 處理常式類別。
這個網域類別參與之關聯性的存取子屬性。（角色屬性沒有巢狀的類別。)

在範例 DSL 中，Comment 類別具有存取子，可透過內嵌關聯性 ComponentModelHasComments 來存取其父模型。
建構函式。如果您想要覆寫這些，設定 有自訂建構函式 網域類別上。
項目群組原型 (EGP) 處理常式方法。這是如果使用者將必須合併（新增）到此類別的執行個體上的另一個項目。通常使用者這麼拖曳項目工具或另一個圖形，或貼上。

此範例 DSL 中，輸入連接埠或輸出連接埠可以合併到元件。此外，元件和註解」可合併模型。此

元件類別中的 EGP 處理常式方法可讓元件接受連接埠，但不是註解。根模型類別中的 EGP 處理常式可接受的註解和元件，但不是連接埠。

DomainModel.cs

表示網域模型的類別。它衍生自 DomainModel。

注意

這不是模型的根類別相同。

複製和 Delete Closure 定義其他項目應該是包含項目會複製或刪除時。您可以設定來控制這個行為 傳播複本 和 傳播刪除 上的每個關聯性每一端之角色的屬性。如果您想要動態決定的值，您可以撰寫程式碼來覆寫 Closure 類別的方法。如需詳細資訊，請參閱 How to︰程式複製和貼上行為-重新導向。

DomainModelResx.resx

這包含其他網域類別和屬性、屬性名稱、工具箱標籤、標準錯誤訊息和其他可能對使用者顯示的字串描述。它也包含工具圖示和影像圖形影像。

這個檔案所建置的組件中，繫結，並提供這些資源的預設值。您可以藉由建立附屬組件，其中包含當地語系化的資源當地語系化您的 DSL。比對的當地語系化的資源的文化特性中安裝 DSL 時，將使用該版本。如需詳細資訊，請參閱部署網域指定的語言方案。

DomainRelationships.cs

每個模型中的兩個項目之間的連結會以網域關聯性類別的執行個體。所有關聯性類別衍生自中繼角色, ，而後者又衍生自 ModelElement。因為這是 ModelElement，關聯性的執行個體可以有屬性，並可以是來源或目標的關聯性。

HelpKeywordHelper.cs

提供使用者按下 F1 鍵時所使用的函式。

MultiplicityValidation.cs

在您用來指定 1..1 或 1 的多重性的關聯性角色..*，應警告使用者須有關聯性至少一個執行個體。這個檔案提供實作這些警告的驗證條件約束。 1..1 不會驗證內嵌父連結。

若要執行這些條件約束，您必須已經設定的其中一個 ...使用 選項 編輯器 \ 驗證 DSL 總管] 中的節點。如需詳細資訊，請參閱驗證定義域專屬語言。

PropertiesGrid.cs

只有當您附加自訂型別描述項的網域屬性，這個檔案包含程式碼。如需詳細資訊，請參閱 [自訂屬性] 視窗](../Topic/Customizing%20the%20Properties%20Window.md)。

SerializationHelper.cs

驗證方法，以確保沒有兩個項目，會參考相同的 moniker。如需詳細資訊，請參閱自訂檔案儲存體和 XML 序列化。
SerializationHelper 類別，提供序列化類別共同使用的函式。

Serializer.cs

每個網域類別、關聯性、圖形、連接器、圖表和模型的序列化程式類別。

這些類別的功能大多可以控制下的 DSL 總管] 中的設定 Xml 序列化行為。

Shapes.cs

在 DSL 定義中的每個圖形類別的類別。圖形衍生自 NodeShape。如需詳細資訊，請參閱自訂檔案儲存體和 XML 序列化。

若要覆寫產生的方法，以您自己的方法，在部分類別中，設定 產生雙衍生 DSL 定義中的連接器。若要建構函式取代成您自己的程式碼，請設定 有自訂建構函式。

若要將執行階段的色彩和其他一些樣式功能變數，以滑鼠右鍵按一下 DSL 定義圖上的類別，並指向 加入已公開。

若要將其他樣式功能變數在執行階段，請參閱例如 TextField 和 ShapeElement

ToolboxHelper.cs

設定 [工具箱] 項目群組原型安裝到項目工具。當使用者執行此工具與目標項目合併這些原型的複本。

您可以覆寫 CreateElementPrototype() 定義工具箱項目，以建立數個物件的群組。例如，您可以定義項目來表示內含子元件的物件。變更程式碼之後，請重設 Visual Studio 的實驗執行個體以清除工具箱快取。

在 DslPackage 專案中產生的檔案

DslPackage 會與 DSL 模型結合為 Visual Studio Shell，以管理視窗、工具箱和功能表命令。大部分的類別是雙衍生類別，以便您可以覆寫其任何方法。

CommandSet.cs

會顯示在圖表上的內容功能表命令。您可以調整，或加入這組。這個檔案包含命令的程式碼。在功能表上的命令的位置取決於 Commands.vsct 檔。如需詳細資訊，請參閱撰寫使用者命令和動作。

Constants.cs

GUID。

DocData.cs

您的 Dsl DocData 管理載入和儲存模型檔案，並建立存放區執行個體。

例如，如果您要在資料庫 (而不是檔案) 中儲存 DSL，您可以覆寫 Load 和 Save 方法。

DocView.cs

您的 Dsl DocView 管理顯示圖表的視窗。比方說，您可以將內嵌在視窗表單圖表︰

將使用者控制項檔案加入至 DslPackage 專案中。加入的面板，可以顯示圖表中。加入按鈕和其他控制項。在表單的程式碼檢視中，新增下列程式碼，調整您的 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

具現化 DocData 和 DocView。這個檔案執行 Visual Studio 在啟動您的 DSL 封裝時用於開啟編輯器的標準介面。 Package.cs 中的 ProvideEditorFactory 屬性會參考這個檔案。

GeneratedVSCT.vsct

[圖表] 內容功能表中，會找出的標準功能表命令編輯 ] 功能表上，依此類推。命令的程式碼位於 CommandSet.cs。您可以重新配置或修改標準的命令，而且您可以新增自己的命令。如需詳細資訊，請參閱撰寫使用者命令和動作。

ModelExplorer.cs

定義您的 dsl 模型總管]。這是模型的使用者會在圖表旁看到的樹狀檢視。

例如，您可以覆寫 InsertTreeView()，變更模型總管中項目的顯示順序。

如果您想要保留已同步處理與圖表選取 [模型總管] 中的選取範圍時，您可以使用下列程式碼︰

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

定義顯示模型總管] 的視窗。處理的 [總管] 中的項目。

Package.cs

這個檔案定義 DSL 與 Visual Studio 的整合方式。在套件類別上的屬性可將 DSL 註冊為副檔名的檔案、定義其工具箱; 以及定義如何開啟新視窗中的檔案處理常式。將第一個 DSL 載入至 Visual Studio 執行個體時，會呼叫 Initialize() 方法一次。

Source.extension.vsixmanifest

若要自訂這個檔案，請編輯 .tt 檔。

警告

如果您編輯.tt 檔，以納入圖示或影像等資源，請確定資源是否包含在 VSIX 組建中。在 [方案總管] 中，選取檔案，並請確定 Include in VSIX 屬性是 True。

此檔案控制如何將 DSL 封裝成 Visual Studio 整合擴充功能 (VSIX)。如需詳細資訊，請參閱部署網域指定的語言方案。

請參閱

如何定義定義域專屬語言
 了解模型、類別和關聯性
 自訂及擴充定義域專屬語言
 撰寫程式碼來自訂定義域專屬語言

共用方式為

了解 DSL 程式碼

範例方案︰元件圖表

DSL 方案的結構

程式碼目錄

在 Dsl 中產生的檔案

在 DslPackage 專案中產生的檔案

請參閱

其他資源

共用方式為

了解 DSL 程式碼

範例方案︰ 元件圖表

DSL 方案的結構

程式碼目錄

在 Dsl 中產生的檔案

在 DslPackage 專案中產生的檔案

請參閱

其他資源

範例方案︰元件圖表