diff --git a/docs/modeling/getting-started-with-domain-specific-languages.md b/docs/modeling/getting-started-with-domain-specific-languages.md index ecd9e6127ef..4cb8a14872d 100644 --- a/docs/modeling/getting-started-with-domain-specific-languages.md +++ b/docs/modeling/getting-started-with-domain-specific-languages.md @@ -1,8 +1,8 @@ --- title: Getting Started with Domain-Specific Languages description: Explore the basic concepts to define and use a domain-specific language (DSL) created with the Modeling SDK for Visual Studio. -ms.date: 11/04/2016 -ms.topic: get-started +ms.date: 11/13/2025 +ms.topic: conceptual author: mgoertz-msft ms.author: mgoertz manager: mijacobs @@ -15,7 +15,7 @@ This topic explains the basic concepts in defining and using a domain-specific l > [!NOTE] > The Text Template Transformation SDK and the Visual Studio Modeling SDK are installed automatically when you install specific features of Visual Studio. For more details, see [this blog post](https://devblogs.microsoft.com/devops/the-visual-studio-modeling-sdk-is-now-available-with-visual-studio-2017/). -If you are new to DSLs, we recommend that you work through the **DSL Tools Lab**, which you can find in this site: [Visualization and Modeling SDK](https://code.msdn.microsoft.com/Visualization-and-Modeling-313535db) +If you are new to DSLs, we recommend that you work through the **VMSDK Lab**, which you can find in this [repository](https://github.com/lumon-Ind/VMSDK-Labs.git) ## What can you do with a Domain-Specific Language? @@ -23,7 +23,7 @@ A domain-specific language is a notation, usually graphical, that is designed to When you have designed a DSL, you can distribute it as part of a Visual Studio Integration Extension (VSIX) package. Users work with the DSL in Visual Studio: -![Family tree diagram, toolbox, and explorer](../modeling/media/familyt_instance.png) +![Family tree diagram, toolbox, and explorer](../modeling/media/tudors-family-tree.png) The notation is only part of a DSL. Together with the notation, your VSIX package includes tools that users can apply to help them edit and generate material from their models. @@ -37,9 +37,10 @@ To define a DSL, you must have installed the following components: | Component | Link | |-|-| -| Visual Studio | [http://go.microsoft.com/fwlink/?LinkId=185579](https://visualstudio.microsoft.com) | -| Visual Studio SDK | [https://go.microsoft.com/fwlink/?linkid=2166172](../extensibility/visual-studio-sdk.md) | -| Modeling SDK for Visual Studio | | +| Visual Studio (any edition)| [http://go.microsoft.com/fwlink/?LinkId=185579](https://visualstudio.microsoft.com) | +| Select the **Visual Studio extension development** workload (includes **Visual Studio SDK**) | [https://go.microsoft.com/fwlink/?linkid=2166172](../extensibility/visual-studio-sdk.md) | +| **Modeling SDK** (not installed by default)| | +| **Class Designer** (not installed by default)| "Code tools" section in the installer's tab **Individual Components** | [!INCLUDE[modeling_sdk_info](includes/modeling_sdk_info.md)] @@ -49,31 +50,41 @@ To create a new domain-specific language, you create a new Visual Studio solutio 1. On the **File** menu, point to **New**, and then click **Project**. -2. Under **Project types**, expand the **Other Project Types** node, and click **Extensibility**. +2. **Create a new project.** + - In the search field type **domain** -3. Click **Domain-Specific Language Designer**. + - Click **Domain-Specific Language Designer**, and then click **Next**. - ![Create DSL dialog](../modeling/media/create_dsldialog.png) + ![Create a new DSL project](../modeling/media/create-new-domain-specific-language-project.png) -4. In the **Name** box, type **FamilyTree**. Click **OK**. +3. **Configure your new project**. - The **Domain-Specific Language Wizard** opens, and displays a list of template DSL solutions. + ![Configure your new project](../modeling/media/create-your-new-project.png) - Click each template to see a description, + - In the **Project name** box, type **FamilyTree**. Click **Create**. +5. The **Domain-Specific Language Designer Wizard** opens, and displays a list of template DSL solutions. + + ![Minimal Language template](../modeling/media/minimal-language-project-template.png) + + - Click each template to see a description, The templates are useful starting points. Each of them provides a complete working DSL, which you can edit to suit your needs. Ordinarily, you would choose the template nearest what you want to create. -5. For this walkthrough, choose the **Minimal Language** template. + - For this walkthrough, choose the **Minimal Language** template. Click **Next**. +6. **Define New Model File Type** -6. Enter a file name extension for your DSL in the appropriate wizard page. This is the extension that files containing instances of your DSL will use. + ![Define new model file type](../modeling/media/define-new-model-file-type.png) - - Choose an extension that is not associated with any application in your computer, or in any computer where you want to install the DSL. For example, **docx** and **htm** would be unacceptable file name extensions. + - Enter a file name extension **ftree** for your DSL in the field **What extension should model files use?**. This is the extension that files containing instances of your DSL will use. + > [!IMPORTANT] + > You must choose an extension that is not associated with any application in your computer, or in any computer where you want to install the DSL. For example, **docx** and **htm** would be unacceptable file name extensions. + > The wizard will warn you if the extension that you have entered is being used as a DSL. In this case consider using a different file name extension. You can also reset the Visual Studio SDK Experimental instance to clear out old experimental designers. In the Windows **Start** menu, type **Reset the Visual Studio**, and then run the **Reset the Microsoft Visual Studio Experimental Instance** command matching your version of Visual Studio. - - The wizard will warn you if the extension that you have entered is being used as a DSL. Consider using a different file name extension. You can also reset the Visual Studio SDK Experimental instance to clear out old experimental designers. In the Windows **Start** menu, type **reset the Visual Studio**, and then run the **Reset the Microsoft Visual Studio Experimental Instance** command matching your version of Visual Studio. +7. Inspect the other pages (click **Next**) and then click **Finish**. -7. Inspect the other pages and then click **Finish**. + ![DSL Solution Summary](../modeling/media/domain-specific-language-solution-summary.png) - A solution is generated that contains two projects. They are named Dsl and DslPackage. A diagram file opens that is named DslDefinition.dsl. + A solution is generated that contains two projects. They are named **Dsl** and **DslPackage**. A diagram file opens that is named **DslDefinition.dsl**. > [!NOTE] > Most of the code that you can see in the folders in the two projects is generated from DslDefinition.dsl. For this reason, most modifications to your DSL are made in this file. @@ -100,10 +111,10 @@ You can run the DSL solution as soon as you have created it. Later, you can modi ### To experiment with the DSL -1. Click **Transform All Templates** in the **Solution Explorer** toolbar. This regenerates most of the source code from DslDefinition.dsl. +1. Click **Transform All T4 Templates** on the **Build** menu. This regenerates most of the source code from DslDefinition.dsl. > [!NOTE] - > Whenever you change *DslDefinition.dsl*, you must click **Transform All Templates** before you rebuild the solution. You can automate this step. For more information, see [How to Automate Transform All Templates](/previous-versions/visualstudio/visual-studio-2012/ff521399\(v\=vs.110\)). + > Whenever you change *DslDefinition.dsl*, you must click **Transform All T4 Templates** before you rebuild the solution. You can automate this step. For more information, see [How to Automate Transform All Templates](/previous-versions/visualstudio/visual-studio-2012/ff521399\(v\=vs.110\)). 2. Press **F5**, or on the **Debug** menu, click **Start Debugging**. @@ -111,15 +122,15 @@ You can run the DSL solution as soon as you have created it. Later, you can modi An experimental instance of Visual Studio starts. The experimental instance takes its settings from a separate subtree of the registry, where Visual Studio extensions are registered for debugging purposes. Normal instances of Visual Studio do not have access to extensions registered there. -3. In the experimental instance of Visual Studio, open the model file named **Test** from **Solution Explorer**. +3. In the experimental instance of Visual Studio, open the model file named **Sample.ftree** from **Solution Explorer**. \- or - - Right-click the Debugging project, point to **Add**, and then click **Item**. In the **Add Item** dialog box, select the file type of your DSL. + Right-click the Debugging project, point to **Add**, and then click **New Item...**. In the **Add New Item** dialog box, select the file type of your DSL (**FamilyTree** in our example). The model file opens as a blank diagram. - The toolbox opens and displays tools appropriate to the diagram type. + The toolbox opens and displays tools appropriate to the diagram type. Or you can show up the toolbox by clicking the menu **View / Toolbox**. 4. Use the tools to create shapes and connectors on the diagram. @@ -131,7 +142,7 @@ You can run the DSL solution as soon as you have created it. Later, you can modi Your experimental Visual Studio will resemble the following example: -![Domain specific language sample tree in Visual Studio](../modeling/media/dsl_min.png) +![Domain specific language sample tree in Visual Studio](../modeling/media/family-tree-model-sample.png) ### The Content of a Model @@ -163,7 +174,7 @@ When you change a model file, you will see corresponding changes in generated fi 2. Make sure that the file name parameter in each .tt file refers to the model file that you are using for experiments. Save the .tt file. -3. Click **Transform All Templates** in the toolbar of **Solution Explorer**. +3. Click **Transform All T4 Templates** on the **Build** menu. \- or - @@ -185,7 +196,7 @@ When you want to modify the DSL definition, close the experimental instance and You can make a wide variety of extensions to your DSL. The following examples will give you an impression of the possibilities. -After each change, save the DSL definition, click **Transform All Templates** in **Solution Explorer**, and then press **F5** to experiment with the changed DSL. +After each change, save the DSL definition, Click **Transform All T4 Templates** on the **Build** menu, and then press **F5** to experiment with the changed DSL. ### Rename the Types and Tools @@ -193,9 +204,9 @@ Rename the existing domain classes and relationships. For example, starting from #### To rename domain classes, relationships and tools -1. In the DslDefinition diagram, rename **ExampleModel** to **FamilyTreeModel**, **ExampleElement** to **Person**, **Targets** to **Parents**, and **Sources** to **Children**. You can click each label to change it. +1. In the DslDefinition diagram, rename **ExampleModel** to **FamilyTreeModel**, **ExampleElement** to **Person**, **Targets** to **Children** (and Name to **Parent** ), **Sources** to **Parents** (and Name to **Child**), **Elements** to **People**, and the DomainRelationship **PersonReferencesChildren** to **ParentsHaveChildren**. Also rename the diagram element **ExampleConnector** to **ChildConnector**. You can click each label to change it. - ![DSL Definition diagram - family tree model](../modeling/media/familyt_person.png) + ![DSL Definition diagram - family tree model](../modeling/media/family-definition-diagram.png) 2. Rename the element and connector tools. @@ -211,48 +222,68 @@ Rename the existing domain classes and relationships. For example, starting from Notice that the **Caption** property also changes. - 6. In the same manner, change the name of the **ExampleConnector** tool to **ParentLink**. Alter the **Caption** property so that it is not a copy of the Name property. For example, enter **Parent Link**. + 6. In the same manner, change the name of the **ExampleRelationship** tool to **ChildLink**. Alter the **Caption** property so that it is not a copy of the Name property. For example, enter **Child Link**. 3. Rebuild the DSL. 1. Save the DSL Definition file. - 2. Click **Transform All Templates** in the toolbar of Solution Explorer + 2. Click **Transform All T4 Templates** on the **Build** menu. 3. Press F5. Wait until the experimental instance of Visual Studio appears. -4. In the Debugging solution in the experimental instance of Visual Studio, open a test model file. Drag elements onto it from the toolbox. Notice that the tool captions and the type names in DSL Explorer have changed. +4. In the Debugging solution in the experimental instance of Visual Studio, open a **Test.ftree** model file. Drag elements onto it from the toolbox. Notice that the tool captions and the type names in Toobox have changed. 5. Save the model file. -6. Open a .tt file and replace occurrences of the old type and property names with the new names. +6. In Solution Explorer open a .tt file (FamilyTreeReport.tt) and replace occurrences of the old type and property names with the new names. 7. Make sure that the file name that is specified in the .tt file specifies your test model. -8. Save the .tt file. Open the generated file to see the result of running the code in the .tt file. Verify that it is correct. +```T4 +<#@ template inherits="Microsoft.VisualStudio.TextTemplating.VSHost.ModelingTextTransformation" #> +<#@ output extension=".txt" #> +<#@ FamilyTree processor="FamilyTreeDirectiveProcessor" requires="fileName='Test.ftree'" #> + +Generated material. Generating code in C#. + +<# + // When you change the DSL Definition, some of the code below may not work. + + foreach (Person person in this.FamilyTreeModel.People) + { +#> + <#= person.Name #> +<# + } +#> +``` + +8. Save the .tt file. Click **OK** in Security Warning dialog box. Open the generated file to see the result of running the code in the .tt file. Verify that it is correct. + +Close the experimental instance of Visual Studio. ### Add Domain Properties to Classes Add properties to a domain class, for example to represent the years of birth and death of a Person. To make the new properties visible on the diagram, you must add *decorators* to the shape that displays the model element. You must also map the properties to the decorators. - ##### To add properties and display them 1. Add the properties. 1. In the DSL Definition diagram, right-click the **Person** domain class, point to **Add**, and then click **Domain Property**. - 2. Type a list of new property names, such as **Birth** and **Death**. Press **Enter** after each one. + 2. Type a list of new property names, such as **BirthYear** and **DeathYear**. Press **Enter** after each one. Select each new domain property, and in the Properties window, set the Type field to **Int32**. 2. Add decorators that will display the properties in the shape. - 1. Follow the gray line that extends from the Person domain class to the other side of the diagram. This is a diagram element map. It links the domain class to a shape class. + 1. Follow the gray line that extends from the Person domain class to the other side of the diagram. This is a diagram element map. It links the domain class to a shape class. Rename the **ExampleShape** to **PersonShape** and change the field **Geometry** to **RoundedRectangle** in the Properties. 2. Right-click this shape class, point to **Add**, and then click **Text Decorator**. - 3. Add two decorators with names such as **BirthDecorator** and **DeathDecorator**. + 3. Add two decorators with names such as **BirthDecorator** and **DeathDecorator**. Add one more text decorator with name **Dash** and set the **Default Text** property to **--** value (two dashes). - 4. Select each new decorator, and in the Properties window, set the **Position** field. This determines where the domain property value will be displayed on the shape. For example, set **InnerBottomLeft** and **InnerBottomRight**. + 4. Select each new decorator, and in the Properties window, set the **Position** field. This determines where the domain property value will be displayed on the shape. For example, set **InnerBottomLeft** and **InnerBottomRight** for BirthDecorator and DeathDecorator respectively. For **Dash** set the Position property to **InnerBottomCenter**. ![Compartment shape definition](../modeling/media/familyt_compartment.png) @@ -262,15 +293,46 @@ Rename the existing domain classes and relationships. For example, starting from 2. On the DSL definition diagram, click the line that connects the **Person** domain class to the shape class. - 3. In **DSL Details**, on the **Decorator Maps** tab, click the check box on an unmapped decorator. In **Display Property**, select the domain property to which you want it mapped. For example, map **BirthDecorator** to **Birth**. + 3. In **DSL Details**, on the **Decorator Maps** tab, click the check box on an unmapped decorator. In **Display property**, select the domain property to which you want it mapped. For example, map **BirthDecorator** to **BirthYear**. Map the **DeathYear** domain properity to their text decorator too. + +![Mapping domain property to text decorator](../modeling/media/family-map-property-decorator.png) + +4. Save the DSL, click **Transform All T4 Templates** on the **Build** menu, and press F5. -4. Save the DSL, click Transform All Templates, and press F5. +5. Add new **FamilyTree** item with name **Tudors.ftree** in the **Debugging** project. In **Tudors.ftree** model diagram, add new **Persons**, **Child Links** and verify that you can now click the positions you chose and type values into them. In addition, when you select a **Person** shape, the Properties window displays the new properties **Birth Year** and **Death Year**. -5. In a sample model diagram, verify that you can now click the positions you chose and type values into them. In addition, when you select a **Person** shape, the Properties window displays the new properties Birth and Death. +![Tudors](../modeling/media/tudors-family-tree.png) 6. In a .tt file, you can add code that obtains the properties of each person. +**FamilyTreeReport.tt**: +```T4 +<#@ template inherits="Microsoft.VisualStudio.TextTemplating.VSHost.ModelingTextTransformation" #> +<#@ output extension=".txt" #> +<#@ FamilyTree processor="FamilyTreeDirectiveProcessor" requires="fileName='Tudors.ftree'" #> - ![Family tree diagram, toolbox, and explorer](../modeling/media/familyt_instance.png) +Generated material. + +<# + // When you change the DSL Definition, some of the code below may not work. + + foreach (Person person in this.FamilyTreeModel.People) + { +#> + <#= person.Name #> (<#= person.BirthYear #> - <#= person.DeathYear #>) +<# + } +#> +``` +Generated **FamilyTreeReport.txt**: +```Text + +Generated material. + + Henry VIII (1491 - 1547) + Mary I (1516 - 1558) + Elizabeth I (1533 - 1603) + +``` ### Define New Classes You can add domain classes and relationships to a model. For example, you could create a new class to represent towns, and a new relationship to represent that a person lived in a town. @@ -281,7 +343,7 @@ Rename the existing domain classes and relationships. For example, starting from 1. Add a domain class and make it a child of the model root. - 1. In the DSL Definition diagram, click the **Embedding Relationship** tool, click the root class **FamilyTreeModel**, and then click in an empty part of the diagram. + 1. Open the DSL Definition diagram (DslDefinition.dsl). In the Toolbox, click the **Embedding Relationship** tool, click the root class **FamilyTreeModel** in the DSL Definition diagram, and then click in an empty part of the diagram. A new domain class appears, that is connected to the FamilyTreeModel with an embedding relationship. @@ -294,20 +356,22 @@ Rename the existing domain classes and relationships. For example, starting from 2. Add a reference relationship between Person and Town. - 1. Click the **Reference Relationship** tool, click Person and then click Town. + 1. Click the **Reference Relationship** tool, click Town and then click Person. + 2. Rename **TownReferencesPersons** relationship to **Residence**. + 3. Rename **Persons** on the left of Residence to **Residents**, and **Towns** to **Residences** on the ritght. - ![DSL definition fragment: family tree root](../modeling/media/familyt_root.png) + ![DSL definition fragment: family tree root](../modeling/media/family-tree-towns.png) > [!NOTE] > Reference relationships represent cross-references from one part of the model tree to another. 3. Add a shape to represent towns on the model diagrams. - 1. Drag a **Geometry Shape** from the toolbox to the diagram and rename it, for example **TownShape**. + 1. Drag a **Geometry Shape** from the Toolbox to the diagram and rename it, for example **TownShape**. 2. In the Properties window, set the Appearance fields of the new shape, such as Fill Color and Geometry. - 3. Add a Decorator to display the name of the town, and rename it NameDecorator. Set its Position property. + 3. Add a Text Decorator to display the name of the town, and rename it NameDecorator. Set its Position property. 4. Map the Town domain class to the TownShape. @@ -321,7 +385,7 @@ Rename the existing domain classes and relationships. For example, starting from 2. Use the **Diagram Element Map** tool to link the new connector to the relationship between Person and Town. - ![Family Tree definition with added shape map](../modeling/media/familyt_shapemap.png) + ![Family Tree definition with added shape map](../modeling/media/family-town-shape-map.png) 6. Create an element tool for making a new Town. @@ -331,48 +395,64 @@ Rename the existing domain classes and relationships. For example, starting from 3. Set the **Name** property of the new tool, and set its **Class** property to Town. - 4. Set the **Toolbox Icon** property. Click **[...]** and in the **File name** field, select an icon file. + 4. Set the **Toolbox Icon** property. Click **[...]** and in the **File name** field, select an icon file "Resources\ExampleShapeToolBitmap.bmp". 7. Create a connector tool for making a link between towns and people. - 1. Right-click *\* and then click **Add New Connector Tool**. + 1. Right-click *\* and then click **Add New Connection Tool**. 2. Set the Name property of the new tool. - 3. In the **ConnectionBuilder** property, select the builder that contains the name of the Person-Town relationship. + 3. In the **ConnectionBuilder** property, select the ResidenceBuilder. + + 4. Set the **Toolbox Icon** (file "Resources\ExampleConnectorToolBitmap.bmp"). + +8. Save the DSL Definition, click **Transform All T4 Templates**, and then press **F5**. + +9. In the experimental instance of Visual Studio, open a Tudors.ftree model file. Use the new tools to create towns and links between towns and persons. Notice that you can only create links between the correct types of element. + +10. Create code that lists the town in which each person lives. Text templates are one of the places where you can run such code. For example, you could modify the existing FamilyTreeReport.tt file in the Debugging solution so that it contains the following code: - 4. Set the **Toolbox Icon**. +``` +<#@ template inherits="Microsoft.VisualStudio.TextTemplating.VSHost.ModelingTextTransformation" #> +<#@ output extension=".txt" #> +<#@ FamilyTree processor="FamilyTreeDirectiveProcessor" requires="fileName='Tudors.ftree'" #> -8. Save the DSL Definition, click **Transform All Templates**, and then press **F5**. -9. In the experimental instance of Visual Studio, open a test model file. Use the new tools to create towns and links between towns and persons. Notice that you can only create links between the correct types of element. +<# +foreach (Person person in this.FamilyTreeModel.People) +{ +#> +<#= person.Name #> (<#= person.BirthYear #> - <#= person.DeathYear #>) +<#if (person.Residences != null) #> Residences:<# +foreach(Town town in person.Residences) {#><#= town.Name #>,<#} +#> +<#if (person.Children.Count > 0) +{#> -10. Create code that lists the town in which each person lives. Text templates are one of the places where you can run such code. For example, you could modify the existing Sample.tt file in the Debugging solution so that it contains the following code: + Children: +<# +foreach(Person child in person.Children) +{ +#> + <#= child.Name #> +<# +} +} +#> - ``` - <#@ template inherits="Microsoft.VisualStudio.TextTemplating.VSHost.ModelingTextTransformation" debug="true" #> - <#@ output extension=".txt" #> - <#@ FamilyTree processor="FamilyTreeDirectiveProcessor" requires="fileName='Sample.ftree'" #> +<# +} +#> + +``` - <# - foreach (Person person in this.FamilyTreeModel.People) - { - #> - <#= person.Name #><#if (person.Town != null) {#> of <#= person.Town.Name #> <#}#> +You can get Class Diagram to understand class structure and use it in the *.tt files. Right click the **DomainClasses.cs** (the subsidiary file of **DomainClasses.tt**) and then click the **View Class Diagram** command. - <# - foreach (Person child in person.Children) - { - #> - <#= child.Name #> - <# - } - } - #> +![Domain Class Diagram](../modeling/media/family-class-diagram.png) - ``` - When you save the *.tt file, it will create a subsidiary file that contains the list of people and their residences. For more information, see [Generating Code from a Domain-Specific Language](../modeling/generating-code-from-a-domain-specific-language.md). +When you save the *.tt file, it will create a subsidiary file that contains the list of people and their residences. For more information, see [Generating Code from a Domain-Specific Language](../modeling/generating-code-from-a-domain-specific-language.md). ## Validation and Commands You could develop this DSL further by adding validation constraints. These constraints are methods that you can define, that make sure that the model is in a correct state. For example, you could define a constraint to make sure that the birth date of a child is later than that of its parents. The validation feature displays a warning if the DSL user tries to save a model that breaks any of the constraints. For more information, see [Validation in a Domain-Specific Language](../modeling/validation-in-a-domain-specific-language.md). diff --git a/docs/modeling/media/create-new-domain-specific-language-project.png b/docs/modeling/media/create-new-domain-specific-language-project.png new file mode 100644 index 00000000000..b2852862792 Binary files /dev/null and b/docs/modeling/media/create-new-domain-specific-language-project.png differ diff --git a/docs/modeling/media/create-your-new-project.png b/docs/modeling/media/create-your-new-project.png new file mode 100644 index 00000000000..26e8b95f759 Binary files /dev/null and b/docs/modeling/media/create-your-new-project.png differ diff --git a/docs/modeling/media/define-new-model-file-type.png b/docs/modeling/media/define-new-model-file-type.png new file mode 100644 index 00000000000..5fe6b3281b7 Binary files /dev/null and b/docs/modeling/media/define-new-model-file-type.png differ diff --git a/docs/modeling/media/domain-specific-language-solution-summary.png b/docs/modeling/media/domain-specific-language-solution-summary.png new file mode 100644 index 00000000000..0fdefe5b4c0 Binary files /dev/null and b/docs/modeling/media/domain-specific-language-solution-summary.png differ diff --git a/docs/modeling/media/family-class-diagram.png b/docs/modeling/media/family-class-diagram.png new file mode 100644 index 00000000000..6720ddbb913 Binary files /dev/null and b/docs/modeling/media/family-class-diagram.png differ diff --git a/docs/modeling/media/family-definition-diagram.png b/docs/modeling/media/family-definition-diagram.png new file mode 100644 index 00000000000..b364222bcdb Binary files /dev/null and b/docs/modeling/media/family-definition-diagram.png differ diff --git a/docs/modeling/media/family-map-property-decorator.png b/docs/modeling/media/family-map-property-decorator.png new file mode 100644 index 00000000000..a758eaaeb07 Binary files /dev/null and b/docs/modeling/media/family-map-property-decorator.png differ diff --git a/docs/modeling/media/family-town-shape-map.png b/docs/modeling/media/family-town-shape-map.png new file mode 100644 index 00000000000..59023191b6f Binary files /dev/null and b/docs/modeling/media/family-town-shape-map.png differ diff --git a/docs/modeling/media/family-tree-model-sample.png b/docs/modeling/media/family-tree-model-sample.png new file mode 100644 index 00000000000..03519252b9f Binary files /dev/null and b/docs/modeling/media/family-tree-model-sample.png differ diff --git a/docs/modeling/media/family-tree-towns.png b/docs/modeling/media/family-tree-towns.png new file mode 100644 index 00000000000..d63371e4ebc Binary files /dev/null and b/docs/modeling/media/family-tree-towns.png differ diff --git a/docs/modeling/media/minimal-language-project-template.png b/docs/modeling/media/minimal-language-project-template.png new file mode 100644 index 00000000000..d04f9aa19f8 Binary files /dev/null and b/docs/modeling/media/minimal-language-project-template.png differ diff --git a/docs/modeling/media/tudors-family-tree.png b/docs/modeling/media/tudors-family-tree.png new file mode 100644 index 00000000000..f8676ddfd3e Binary files /dev/null and b/docs/modeling/media/tudors-family-tree.png differ diff --git a/docs/modeling/modeling-sdk-for-visual-studio-domain-specific-languages.md b/docs/modeling/modeling-sdk-for-visual-studio-domain-specific-languages.md index 0259d315fdf..b6da8fcd555 100644 --- a/docs/modeling/modeling-sdk-for-visual-studio-domain-specific-languages.md +++ b/docs/modeling/modeling-sdk-for-visual-studio-domain-specific-languages.md @@ -3,7 +3,7 @@ title: Use the Modeling SDK for Visual Studio description: Use the Modeling SDK for Visual Studio to create powerful model-based development tools that integrate into Visual Studio. titleSuffix: '' ms.date: 11/04/2016 -ms.topic: concept-article +ms.topic: conceptual helpviewer_keywords: - Domain-Specific Language Tools - Domain-Specific Language @@ -14,11 +14,11 @@ ms.subservice: modeling --- # Modeling SDK for Visual Studio - Domain-Specific Languages -By using the Modeling SDK for Visual Studio, you can create powerful model-based development tools that you can integrate into Visual Studio. In the same manner, you can create one or more model definitions and integrate them into a set of tools. +By using the Modeling SDK for Visual Studio (VMSDK), you can create powerful model-based development tools that you can integrate into Visual Studio. In the same manner, you can create one or more model definitions and integrate them into a set of tools. -At the heart of MSDK is the definition of a model that you create to represent concepts in your business area. You can surround the model with a variety of tools, such as a diagrammatic view, the ability to generate code and other artifacts, commands for transforming the model, and the ability to interact with code and other objects in Visual Studio. As you develop the model, you can combine it with other models and tools to form a powerful toolset that is centered on your development. +At the heart of VMSDK is the definition of a model that you create to represent concepts in your business area. You can surround the model with a variety of tools, such as a diagrammatic view, the ability to generate code and other artifacts, commands for transforming the model, and the ability to interact with code and other objects in Visual Studio. As you develop the model, you can combine it with other models and tools to form a powerful toolset that is centered on your development. -MSDK lets you develop a model quickly in the form of a domain-specific language (DSL). You begin by using a specialized editor to define a schema or abstract syntax together with a graphical notation. From this definition, VMSDK generates: +VMSDK lets you develop a model quickly in the form of a domain-specific language (DSL). You begin by using a specialized editor to define a schema or abstract syntax together with a graphical notation. From this definition, VMSDK generates: - A model implementation with a strongly-typed API that runs in a transaction-based store. diff --git a/docs/modeling/validation-in-a-domain-specific-language.md b/docs/modeling/validation-in-a-domain-specific-language.md index 2456360dba0..fc1aff6292e 100644 --- a/docs/modeling/validation-in-a-domain-specific-language.md +++ b/docs/modeling/validation-in-a-domain-specific-language.md @@ -1,8 +1,8 @@ --- title: Validation in a Domain-Specific Language description: Learn how you can define validation constraints to verify that the model created by the user is meaningful. -ms.date: 11/04/2016 -ms.topic: article +ms.date: 11/13/2025 +ms.topic: conceptual helpviewer_keywords: - Domain-Specific Language, constraints - Domain-Specific Language, validation @@ -83,6 +83,8 @@ As the author of a domain-specific language (DSL), you can define validation con using Microsoft.VisualStudio.Modeling; using Microsoft.VisualStudio.Modeling.Validation; +namespace Company.FamilyTree +{ // Allow validation methods in this class: [ValidationState(ValidationState.Enabled)] // In this DSL, ParentsHaveChildren is a domain relationship @@ -116,6 +118,7 @@ public partial class ParentsHaveChildren this.Parent); } } +} ``` Notice the following points about this code: @@ -141,7 +144,7 @@ public partial class ParentsHaveChildren |Category|Execution| |-|-| -||When the user invokes the Validate menu command.| +||When the user invokes the Validate menu command.| ||When the model file is opened.| ||When the file is saved. If there are validation errors, the user will be given the option of canceling the save operation.| ||When the file is saved. If there are errors from methods in this category, the user is warned that it might not be possible to re-open the file.

Use this category for validation methods that test for duplicated names or IDs, or other conditions that might cause loading errors.|