網域指定的語言中的驗證

發行項
10/07/2023

身為網域指定的語言 (DSL) 的作者，您可以定義驗證條件約束，以驗證使用者建立的模型是否有意義。例如，如果您的 DSL 允許使用者繪製人們與其祖先的家譜，您可以撰寫條件約束，確保孩子的出生日期晚於父母的出生日期。

您可以在儲存模型時、開啟模型時，以及使用者明確執行 [驗證] 功能表命令時，執行驗證條件約束。您也可以在程式控制下執行驗證。例如，您可以執行驗證，以回應屬性值或關聯性的變更。

如果您要撰寫文字範本或其他工具來處理使用者的模型，驗證便特別重要。驗證可確保模型滿足這些工具假設的前置條件。

警告

除了擴充功能的功能表命令和軌跡處理常式之外，您也可以將驗證條件約束定義為 DSL 的個別擴充功能。當使用者安裝 DSL 時，可以另外選擇安裝這些擴充功能。如需詳細資訊，請參閱使用 MEF 擴充您的 DSL。

執行驗證

當使用者編輯模型 (亦即網域指定的語言執行個體) 時，下列動作會執行驗證：

以滑鼠右鍵按一下圖表並選取 [全部驗證]。
以滑鼠右鍵按一下 [DSL 總管] 中的最上層節點，並選取 [全部驗證]
儲存模型。
開啟模型。
此外，您可以撰寫執行驗證的程式碼，以做為功能表命令的一部分或回應變更。

任何驗證錯誤都會顯示在 [錯誤清單] 視窗中。使用者可以按兩下錯誤訊息，選取造成錯誤的模型項目。

定義驗證條件約束

您可以將驗證方法加入至 DSL 的網域類別或關聯性，藉此定義驗證條件約束。當使用者執行驗證或在程式控制下執行驗證時，即會執行部分或所有驗證方法。每個方法都會套用至其類別的每個執行個體，並且每個類別中可以有數個驗證方法。

每個驗證方法會報告找到的任何錯誤。

注意

驗證方法會報告錯誤，但不會變更模型。如果您要調整或避免特定變更，請參閱驗證的替代方法。

定義驗證條件約束

在編輯器\驗證節點中啟用驗證：
1. 開啟 DslDefinition.dsl。
2. 在 [DSL 總管] 中，展開 [編輯器] 節點並選取 [驗證]。
3. 在 [屬性] 視窗中，將 Uses 屬性設定為 true。最方便的做法是設定所有屬性。
4. 在 [方案總管] 工具列中，按一下 [轉換所有範本]。
撰寫一個或多個網域類別或網域關聯性的部分類別定義。在 Dsl 專案的新程式碼檔案中，撰寫這些定義。
在每個類別的前面加上下列屬性：
```
[ValidationState(ValidationState.Enabled)]
```
- 根據預設，這個屬性也會啟用衍生類別的驗證。如果您要停用特定衍生類別的驗證，您可以使用 ValidationState.Disabled。
將驗證方法加入至類別。每個驗證方法可以命名為任何名稱，但只能有一個 ValidationContext 類型的參數。

此方法的前面必須加上一個或多個 ValidationMethod 屬性：
```
[ValidationMethod (ValidationCategories.Open | ValidationCategories.Save | ValidationCategories.Menu ) ]
```
ValidationCategories 指定何時執行方法。

例如：

using Microsoft.VisualStudio.Modeling;
using Microsoft.VisualStudio.Modeling.Validation;

// Allow validation methods in this class:
[ValidationState(ValidationState.Enabled)]
// In this DSL, ParentsHaveChildren is a domain relationship
// from Person to Person:
public partial class ParentsHaveChildren
{
  // Identify the method as a validation method:
  [ValidationMethod
  ( // Specify which events cause the method to be invoked:
    ValidationCategories.Open // On file load.
  | ValidationCategories.Save // On save to file.
  | ValidationCategories.Menu // On user menu command.
  )]
  // This method is applied to each instance of the
  // type (and its subtypes) in a model:
  private void ValidateParentBirth(ValidationContext context)
  {
    // In this DSL, the role names of this relationship
    // are "Child" and "Parent":
     if (this.Child.BirthYear < this.Parent.BirthYear
        // Allow user to leave the year unset:
        && this.Child.BirthYear != 0)
      {
        context.LogError(
             // Description:
                       "Child must be born after Parent",
             // Unique code for this error:
                       "FAB001ParentBirthError",
              // Objects to select when user double-clicks error:
                       this.Child,
                       this.Parent);
    }
  }

請注意有關這個程式碼的下列重點：

您可以將驗證方法加入至網域類別或網域關聯性。這些類型的程式碼位於 Dsl\Generated Code\Domain*.cs 中。
每個驗證方法會套用至其類別和子類別的每一個執行個體。在網域關聯性的案例中，每個執行個體是兩個模型項目之間的連結。
您無法依任何指定的順序套用驗證方法，也無法依任何預期的順序將每個方法套用至其類別的執行個體。
讓驗證方法更新存放區內容通常不是很好的做法，因為這會導致不一致的結果。相反地，此方法應呼叫 context.LogError、LogWarning 或 LogInfo 來報告任何錯誤。
在 LogError 呼叫中，您可以提供模型項目或關聯性連結的清單，以供使用者按兩下錯誤訊息時選取。
如需如何在程式碼中讀取模型的詳細資訊，請參閱在程式碼中巡覽和更新模型。

此範例會套用至下列網域模型。 ParentsHaveChildren 關聯性具有名為 Child 和 Parent 的角色。

驗證分類

在 ValidationMethodAttribute 屬性中，您可以指定何時應執行驗證方法。

類別	執行
ValidationCategories	使用者叫用 [驗證] 功能表命令時。
ValidationCategories	開啟模型檔時。
ValidationCategories	儲存檔案時。如果發生驗證錯誤，使用者可以選擇取消儲存作業。
ValidationCategories	儲存檔案時。如果此分類的方法發生錯誤，則會警告使用者可能無法重新開啟檔案。使用此分類的驗證方法，來測試是否有重複的名稱或 ID，或者是否有可能造成載入錯誤的其他情況。
ValidationCategories	呼叫 ValidateCustom 方法時。此分類的驗證只能從程式碼叫用。如需詳細資訊，請參閱自訂驗證分類。

驗證方法的位置

對不同的類型套用驗證方法，通常可以達到相同的效果。例如，您可以將方法加入至 Person 類別，而不是 ParentsHaveChildren 關聯性，再讓方法逐一查看連結：

[ValidationState(ValidationState.Enabled)]
public partial class Person
{[ValidationMethod
 ( ValidationCategories.Open
 | ValidationCategories.Save
 | ValidationCategories.Menu
 )
]
  private void ValidateParentBirth(ValidationContext context)
  {
    // Iterate through ParentHasChildren links:
    foreach (Person parent in this.Parents)
    {
        if (this.BirthYear <= parent.BirthYear)
        { ...

彙總驗證條件約束。 若要依預期的順序套用驗證，請在擁有者類別 (例如模型的根項目) 上定義一個驗證方法。這個方法也可讓您將多份錯誤報告彙總成一個訊息。

其缺點在於合併的方法比較難管理，並且條件約束必須具有相同的 ValidationCategories。因此，建議您盡可能以不同的方法來保留每個條件約束。

將值傳入內容快取。 內容參數具有字典，可供您置入任意值。在執行驗證期間都可以使用此字典。例如，某個驗證方法可能會將錯誤計數保留在內容中，然後使用該內容以避免錯誤視窗中出現太多重複的訊息。例如：

List<ParentsHaveChildren> erroneousLinks;
if (!context.TryGetCacheValue("erroneousLinks", out erroneousLinks))
erroneousLinks = new List<ParentsHaveChildren>();
erroneousLinks.Add(this);
context.SetCacheValue("erroneousLinks", erroneousLinks);
if (erroneousLinks.Count < 5) { context.LogError( ... ); }

多重性驗證

您的 DSL 會自動產生用於檢查最小多重性的驗證方法。程式碼會寫入 Dsl\Generated Code\MultiplicityValidation.cs。這些方法會在您於 [DSL 總管] 的 [編輯器\驗證] 節點中啟用驗證時生效。

如果將網域關聯性角色的多重性設定為 1..* 或 1..1，但使用者未建立此關聯性的連結，則會出現驗證錯誤訊息。

例如，如果您的 DSL 具有 Person 和 Town 類別，而關聯性 PersonLivesInTown 在 Town 角色具有關聯性 1..\*，則每個沒有 Town 的 Person 都會出現錯誤訊息。

從程式碼執行驗證

您可以存取或建立 ValidationController 來執行驗證。如果您要在錯誤視窗中向使用者顯示錯誤，請使用連結至您的圖表之 DocData 的 ValidationController。例如，如果您要撰寫功能表命令，可以使用命令集類別中的 CurrentDocData.ValidationController：

using Microsoft.VisualStudio.Modeling;
using Microsoft.VisualStudio.Modeling.Validation;
using Microsoft.VisualStudio.Modeling.Shell;
...
partial class MyLanguageCommandSet
{
  private void OnMenuMyContextMenuCommand(object sender, EventArgs e)
  {
   ValidationController controller = this.CurrentDocData.ValidationController;
...

如需詳細資訊，請參閱如何：將命令新增至快捷方式功能表。

您也可以建立獨立的驗證控制器，自行管理錯誤。例如：

using Microsoft.VisualStudio.Modeling;
using Microsoft.VisualStudio.Modeling.Validation;
using Microsoft.VisualStudio.Modeling.Shell;
...
Store store = ...;
VsValidationController validator = new VsValidationController(s);
// Validate all elements in the Store:
if (!validator.Validate(store, ValidationCategories.Save))
{
  // Deal with errors:
  foreach (ValidationMessage message in validator.ValidationMessages) { ... }
}

發生變更時執行驗證

如果您要確保在模型無效時立即警告使用者，您可以定義執行驗證的存放區事件。如需儲存事件的詳細資訊，請參閱事件處理常式傳播在模型外的變更 (部分機器翻譯)。

除了驗證程式碼之外，請將自訂程式碼檔案加入至您的 DslPackage 專案，其內容類似於下列範例。這個程式碼使用連結至文件的 ValidationController。此控制器會在 Visual Studio 錯誤清單中顯示驗證錯誤。

using System;
using System.Linq;
using Microsoft.VisualStudio.Modeling;
using Microsoft.VisualStudio.Modeling.Validation;
namespace Company.FamilyTree
{
  partial class FamilyTreeDocData // Change name to your DocData.
  {
    // Register the store event handler:
    protected override void OnDocumentLoaded()
    {
      base.OnDocumentLoaded();
      DomainClassInfo observedLinkInfo = this.Store.DomainDataDirectory
         .FindDomainClass(typeof(ParentsHaveChildren));
      DomainClassInfo observedClassInfo = this.Store.DomainDataDirectory
         .FindDomainClass(typeof(Person));
      EventManagerDirectory events = this.Store.EventManagerDirectory;
      events.ElementAdded
         .Add(observedLinkInfo, new EventHandler<ElementAddedEventArgs>(ParentLinkAddedHandler));
      events.ElementDeleted.Add(observedLinkInfo, new EventHandler<ElementDeletedEventArgs>(ParentLinkDeletedHandler));
      events.ElementPropertyChanged.Add(observedClassInfo, new EventHandler<ElementPropertyChangedEventArgs>(BirthDateChangedHandler));
    }
    // Handler will be called after transaction that creates a link:
    private void ParentLinkAddedHandler(object sender,
                                ElementAddedEventArgs e)
    {
      this.ValidationController.Validate(e.ModelElement,
           ValidationCategories.Save);
    }
    // Called when a link is deleted:
    private void ParentLinkDeletedHandler(object sender,
                                ElementDeletedEventArgs e)
    {
      // Don't apply validation to a deleted item!
      // - Validate store to refresh the error list.
      this.ValidationController.Validate(this.Store,
           ValidationCategories.Save);
    }
    // Called when any property of a Person element changes:
    private void BirthDateChangedHandler(object sender,
                      ElementPropertyChangedEventArgs e)
    {
      Person person = e.ModelElement as Person;
      // Not interested in changes in other properties:
      if (e.DomainProperty.Id != Person.BirthYearDomainPropertyId)
          return;

      // Validate all parent links to and from the person:
      this.ValidationController.Validate(
        ParentsHaveChildren.GetLinksToParents(person)
        .Concat(ParentsHaveChildren.GetLinksToChildren(person))
        , ValidationCategories.Save);
    }
  }
}

在影響連結或項目的復原或取消復原作業之後，也會呼叫處理常式。

自訂驗證分類

除了標準驗證分類 (例如功能表和開啟) 之外，您還可以定義自己的分類。您可以從程式碼叫用這些分類。使用者無法直接叫用這些分類。

自訂分類的一般用法是，定義一個分類以測試模型是否滿足特定工具的前置條件。

若要將驗證方法加入至特定分類，請在此方法的前面加上類似如下的屬性：

[ValidationMethod(CustomCategory = "PreconditionsForGeneratePartsList")]
[ValidationMethod(ValidationCategory.Menu)]
private void TestForCircularLinks(ValidationContext context)
{...}

注意

您可以視需要在方法前面加上任意數目的 [ValidationMethod()] 屬性。您可以同時將一個方法加入至自訂分類和標準分類。

若要叫用自訂驗證：


// Invoke all validation methods in a custom category:
validationController.ValidateCustom
  (store, // or a list of model elements
   "PreconditionsForGeneratePartsList");

驗證的替代方法

驗證條件約束會報告錯誤，但不會變更模型。如果您想避免模型無效，可以使用其他方法。

但是，不建議使用這些方法。通常比較好的做法是，讓使用者決定如何修正無效的模型。

調整變更，以恢復成有效的模型。 例如，如果使用者將屬性設得超過允許的上限，您可以將屬性重設為最大值。若要達成目標，請定義規則。如需詳細資訊，請參閱規則在模型內傳播變更 (部分機器翻譯)。

如果嘗試無效的變更，則復原異動。 您也可以為此目的定義規則，但在某些情況下，您可以覆寫屬性處理常式 OnValueChanging()，或覆寫像是 OnDeleted(). 的方法。若要復原交易，請使用 this.Store.TransactionManager.CurrentTransaction.Rollback().。如需詳細資訊，請參閱網域屬性值變更處理常式。

警告

確定使用者知道已調整或已復原變更。例如，使用 System.Windows.Forms.MessageBox.Show("message").

共用方式為

網域指定的語言中的驗證

執行驗證

定義驗證條件約束

定義驗證條件約束

驗證分類

驗證方法的位置

多重性驗證

從程式碼執行驗證

發生變更時執行驗證

自訂驗證分類

驗證的替代方法

意見反應

意見反應

其他資源

共用方式為

網域指定的語言中的驗證

執行驗證

定義驗證條件約束

定義驗證條件約束

驗證分類

驗證方法的位置

多重性驗證

從程式碼執行驗證

發生變更時執行驗證

自訂驗證分類

驗證的替代方法

相關內容

意見反應

意見反應

其他資源