Visual Studio Code を使用して Azure Logic Apps Rules Engine プロジェクトを作成する (プレビュー)

[アーティクル]
06/17/2024

適用対象: Azure Logic Apps (Standard)

重要

この機能はプレビュー段階にあり、「Microsoft Azure プレビューの追加使用条件」が適用されます。

ビジネスロジックを Azure Logic Apps の Standard ワークフローと統合する場合は、Visual Studio Code を使用して Azure Logic Apps Rules Engine プロジェクトを作成してビルドできます。ルールは、ビジネスプロセスのしくみに関するビジネスロジックを管理します。

この攻略ガイドでは、Azure Logic Apps Rules Engine プロジェクトを作成する方法について説明します。

Microsoft Rules Composer を使用してプロジェクトのビジネスルールを作成するなど、Azure Logic Apps Rules Engine プロジェクトを作成するための前提条件とセットアップ。
既存のルールがある場合は、Microsoft BizTalk Server からエクスポートします。
Visual Studio Code を使用して、Azure Logic Apps Rules Engine 用の Standard ロジックアプリプロジェクトを作成します。

前提条件

ルールセット、ビジネスルール、およびボキャブラリの作成に使用する Microsoft Rules Composer をダウンロードしてインストールします。

ルールエンジンプロジェクトのビジネスを構築するには、次のドキュメントを参照してください。
- Microsoft Rules Composer を使用してルールを作成する
- Azure Logic Apps Rules Engine を使用した意思決定管理とビジネスロジックの統合
このリリースでは、Visual Studio Code のみが Azure Logic Apps Rules Engine プロジェクトの開発エクスペリエンスをサポートしています。 Visual Studio Code を使用するための前提条件を満たすには、「Visual Studio Code を使用したシングルテナント Azure Logic Apps で Standard ロジックアプリワークフローを作成する」を参照してください。
Azure Logic Apps Rules Engine は、Visual Studio Code のカスタムコード関数機能を使用します。この機能を使用するための前提条件を満たすには、「Azure Logic Apps の Standard ワークフローから .NET Framework コードを作成して実行する」を参照してください。

プロジェクトを作成する前に

ルールエンジンプロジェクトを確実に成功させるには、次の一般的なタスクとベストプラクティスを確認して実行します。

ビジネスルールがビジネスプロセスにどのように適合するかを決定します。
アプリケーションにビジネスルールを組み込む方法を検討します。
アプリケーション内で、ルールによって表すビジネスロジックを特定します。

"ビジネスロジック" という用語は、多くのことを指すことができます。たとえば、"500 ドルを超える発注書にはマネージャーの承認が必要です" というビジネスロジックが考えられます。
ルール要素のデータソースを特定します。オプションで、ボキャブラリ (基になるバインドを表すドメイン固有の命名規則) を定義できます。
ボキャブラリ定義から、またはデータバインディングから直接使用するルールを定義します。これらのルールから、ビジネスロジックを表すルールセットを作成します。

Microsoft BizTalk Server からルールをエクスポートする

Microsoft BizTalk Server から既存のルールを再利用するには、それらをエクスポートします。ただし、現在、DB ファクトはサポートされていません。ルールをエクスポートする前に、Microsoft BizTalk Rules Composer を使用して、ルールを削除するか、他の種類のファクトにリファクタリングします。

Microsoft BizTalk Server から、ビジネスルールエンジン展開ウィザードを起動します。
[ルールエンジン展開ウィザードへようこそ] ページで、[次へ] を選択します。
[展開タスク] ページで、[ポリシー/ボキャブラリをデータベースからファイルにエクスポートする] を選択し、[次へ] をクリックします。
[ポリシーストア] ページの [SQL Server 名] 一覧で、SQL Server を選択します。選択したサーバーの構成データベースの一覧で BizTalkRuleEngineDb を選択し、[次へ] を選択します。
[ポリシー/ボキャブラリのエクスポート] ページの [ポリシー] 一覧から、目的のポリシーを選択します。定義ファイルを検索して選択するには、[参照する] を選択します。
準備ができたら、 [次へ] を選択します。
サーバー、データベース、ポリシーまたはボキャブラリの情報を確認し、[次へ] を選択します。
インポートまたはエクスポートが完了したら、[次へ] を選択します。
インポートまたはエクスポートの完了状態を確認し、[完了] を選択します。

Azure Logic Apps Rules Engine プロジェクトを作成する

Visual Studio Code のアクティビティバーで、Azure アイコンを選択します。 (キーボード: Shift + Alt + A)
開いたAzure ウィンドウの [ワークスペース] セクションツールバーで、[Azure Logic Apps] メニューから、[新しいプロジェクトの作成] を選択します。
「フォルダー選択」 ボックスで、プロジェクト用に作成したローカルフォルダーを見つけて選択します。
「新しいロジックアプリワークスペースを作成する」 プロンプトボックスが表示されたら、ワークスペースに付ける名前を入力します:

この例では MyLogicAppRulesWorkspace とします。
[ロジックアプリワークスペースのプロジェクトテンプレートを選択してください] プロンプトボックスが表示されたら、[ルールエンジンプロジェクトを使用するロジックアプリ (プレビュー)] を選択します。

後続のプロンプトに従って、次の例の値を指定します:

項目	値の例
関数プロジェクトの関数名	RulesFunction
関数プロジェクトの名前空間名	Contoso.Enterprise
ワークフローテンプレート: - ステートフルワークフロー - ステートレスワークフロー	ステートフルワークフロー
ワークフロー名	MyRulesWorkflow

[Open in current window] (現在のウィンドウで開く) を選択します。

この手順を完了すると、Visual Studio Code でワークスペースが作成されます。例として、既定では、関数プロジェクトとロジックアプリルールのエンジンプロジェクトが含まれます。

Node	説明
*<ワークスペース名>*	関数プロジェクトとロジックアプリワークフロープロジェクトの両方が含まれます。
関数	関数プロジェクトの成果物が含まれます。たとえば、<関数名>.cs ファイルは、コードを作成できるコードファイルです。
ロジックアプリ	ワークフローを含む、ロジックアプリルールのエンジンプロジェクトの成果物が含まれます。

ルールエンジンコードを記述する

ワークスペースで、[関数] ノードを展開します (まだ展開されていない場合)。

この例では、RulesFunction.cs という名前の <関数名>.cs ファイルを開きます。

既定では、このファイルには、次のコード要素を含むサンプルコードと、前に指定した値の例が必要に応じて含まれています。

名前空間名
クラス名
関数名
関数のパラメーター
の戻り値の型 :
複合型

次の例は、RulesFunction という名前の関数の完全なサンプルコードを示しています。

//------------------------------------------------------------
// Copyright (c) Microsoft Corporation. All rights reserved.
//------------------------------------------------------------

namespace Contoso.Enterprise
{
    using System;
    using System.Collections.Generic;
    using System.Threading.Tasks;
    using Microsoft.Azure.Functions.Extensions.Workflows;
    using Microsoft.Azure.WebJobs;
    using Microsoft.Azure.Workflows.RuleEngine;
    using Microsoft.Extensions.Logging;
    using System.Xml;

    /// <summary>
    /// Represents the RulesFunction flow invoked function.
    /// </summary>
    public class RulesFunction
    {
        private readonly ILogger<RulesFunction> logger;

        public RulesFunction(ILoggerFactory loggerFactory)
        {
            logger = loggerFactory.CreateLogger<RulesFunction>();
        }

        /// <summary>
        /// Execute the logic app workflow.
        /// </summary>
        /// <param name="ruleSetName">The ruleset name.</param>
        /// <param name="documentType">The document type for the input XML.</param>
        /// <param name="inputXml">The input XML type fact.</param>
        /// <param name="purchaseAmount">The purchase amount value used to create a .NET fact.</param>
        /// <param name="zipCode">The zip code value used to create a .NET fact.</param>
        [FunctionName("RulesFunction")]
        public Task<RuleExecutionResult> RunRules([WorkflowActionTrigger] string ruleSetName, string documentType, string inputXml, int purchaseAmount, string zipCode)
        {
            /***** Summary of steps below *****
            * 1. Get the ruleset to execute.
            * 2. Check if the ruleset was successfully retrieved.
            * 3. Create the rules engine object.
            * 4. Create TypedXmlDocument facts for all XML document facts.
            * 5. Initialize .NET facts.
            * 6. Execute rules engine.
            * 7. Retrieve relevant updates facts and send them back.
            */

            try
            {
                // Get the ruleset based on the ruleset name.
                 var ruleExplorer = new FileStoreRuleExplorer();
                 var ruleSet = ruleExplorer.GetRuleSet(ruleSetName);

                // Check if ruleset exists.
                if(ruleSet == null)
                {
                    // Log an error if ruleset not found.
                    this.logger.LogCritical($"RuleSet instance for '{ruleSetName}' was not found(null)");
                    throw new Exception($"RuleSet instance for '{ruleSetName}' was not found.");
                }

                // Create rules engine instance.
                var ruleEngine = new RuleEngine(ruleSet: ruleSet);

                // Create one or more typedXmlDcoument facts from one or more input XML documents.
                XmlDocument doc = new XmlDocument();
                doc.LoadXml(inputXml);
                var typedXmlDocument = new TypedXmlDocument(documentType, doc);

                // Initialize .NET facts.
                var currentPurchase = new ContosoNamespace.ContosoPurchase(purchaseAmount, zipCode);

                // Provide facts and run the rules engine.
                ruleEngine.Execute(new object[] { typedXmlDocument, currentPurchase });

                // Send back the relevant results (facts).
                var updatedDoc = typedXmlDocument.Document as XmlDocument;
                var ruleExectionOutput = new RuleExecutionResult()
                {
                    XmlDoc = updatedDoc.OuterXml,
                    PurchaseAmountPostTax = currentPurchase.PurchaseAmount + currentPurchase.GetSalesTax()
                };

                return Task.FromResult(ruleExectionOutput);
            }
            catch(RuleEngineException ruleEngineException)
            {
                // Log any rules engine exceptions.
                this.logger.LogCritical(ruleEngineException.ToString());
                throw;
            }
        }

        /// <summary>
        /// Results from rules execution
        /// </summary>
        public class RuleExecutionResult
        {
            /// <summary>
            /// Rules updated XML document
            /// </summary>
            public string XmlDoc { get; set;}

            /// <summary>
            /// Purchase amount after tax
            /// </summary>
            public int PurchaseAmountPostTax { get; set;}
        }
    }
}

RulesFunction の関数定義には、作業を開始するために使用できる既定の RunRules メソッドが含まれています。このサンプルの RunRules メソッドでは、Azure Logic Apps Rules Engine にパラメーターを渡す方法を示しています。この例では、メソッドはルールセット名、入力ドキュメントの種類、XML ファクト、さらなる処理に必要なその他の値を渡します。

また、<関数名>.cs ファイルは ILogger インターフェイスを持ち、Application Insights リソースへのイベントのロギングのサポートを提供します。例えば、Application Insights にトレース情報を送信し、その情報をワークフローからのトレース情報とともに格納できます:

private readonly ILogger<RulesFunction> logger;

    public RulesFunction(ILoggerFactory loggerFactory)
    {
        logger = loggerFactory.CreateLogger<RulesFunction>();
    }
    <...>

Azure Logic Apps Rules Engine は、次の手順で説明するように動作します。

エンジンは、FileStoreRuleExplorer オブジェクトを使用してルールセットにアクセスします。ルールセットファイルは、Standard ロジックアプリの [ルール] ディレクトリに格納されます。

この例では、ルールセットファイルは SampleRuleSet.xml と呼ばれ、Microsoft Rules Composer を使用して作成されたか、Microsoft BizTalk Server を使用してエクスポートされたものです。
```
var ruleExplorer = new FileStoreRuleExplorer();
var ruleSet = ruleExplorer.GetRuleSet(ruleSetName);

// Check if the ruleset exists.
if(ruleSet == null)
{
    // Log an error if the ruleset isn't found.
    this.logger.LogCritical($"RuleSet instance for '{ruleSetName}' was not found(null)");
    throw new Exception($"RuleSet instance for '{ruleSetName}' was not found.");
}
```
重要

ルールセットは、ファクトへの参照を保持します。 Microsoft Rules Composer は、ファクトのアセンブリを検索して編集用のルールセットを検証します。 Microsoft Rules Composer で SampleRuleSet.xml などのルールセットを開くには、対応する .NET ファクトアセンブリと共にルールセットを配置する必要があります。それ以外の場合は、例外が発生します。
エンジンは ruleSet オブジェクトを使用して RuleEngine オブジェクトのインスタンスを作成します。

RuleEngine オブジェクトは、Execute メソッドを使用してルールのファクトを受け取ります。

この例では、Execute メソッドは 2 つのファクト、typedXmlDocument という名前の XML ファクトと currentPurchase という名前の .NET ファクトを受け取ります。

エンジンの実行後、ファクトの値はエンジンの実行結果の値で上書きされます。

// Create rules engine instance.
var ruleEngine = new RuleEngine(ruleSet: ruleSet);

// Create one or more typedXml facts from one or more input XML documents.
XmlDocument doc = new XmlDocument();
doc.LoadXml(inputXml);
var typedXmlDocument = new TypedXmlDocument(documentType, doc);

// Initialize .NET facts.
var currentPurchase = new ContosoNamespace.ContosoPurchase(purchaseAmount, zipCode);

// Provide facts and run the rules engine.
ruleEngine.Execute(new object[] { typedXmlDocument, currentPurchase });

// Send back the relevant results (facts).
var updatedDoc = typedXmlDocument.Document as XmlDocument;

エンジンは RuleExecutionResult カスタムクラスを使用して、RunRules メソッドに値を返します。

var ruleExectionOutput = new RuleExecutionResult()
{
    XmlDoc = updatedDoc.OuterXml,
    PurchaseAmountPostTax = currentPurchase.PurchaseAmount + currentPurchase.GetSalesTax()
};

return Task.FromResult(ruleExectionOutput);

サンプルの関数コードを独自の関数コードに置き換え、ご自身のシナリオに合わせて既定の RunRules メソッドを編集します。

この例では、変更を加えずにサンプルコードをそのまま使用します。

コードをコンパイルしてビルドする

コードの記述が完了したら、コンパイルしてビルドエラーが存在しないことを確認します。関数プロジェクトには、ビルドタスクが自動的に含まれ、.NET ファクトアセンブリを含むカスタムコードライブラリがコンパイルされ、ワークフローが実行するカスタム関数を検索するロジックアプリプロジェクトの lib\custom フォルダーに追加されます。これらのタスクにより、アセンブリが lib\custom\net472 フォルダーに配置されます。

Visual Studio Code で、[Terminal] (ターミナル) メニューから [New Terminal] (新しいターミナル) を選択します。
表示された作業ディレクトリの一覧から、新しいターミナルの現在の作業ディレクトリとして [関数] を選択します。

Visual Studio Code で、コマンドプロンプトが表示されたターミナルウィンドウが開きます。
[ターミナル] ウィンドウのコマンドプロンプトに、「dotnet restore .\RulesFunction.csproj」と入力します。
コマンドプロンプトが再び表示されたら、「dotnet build .\RulesFunction.csproj」と入力します。

ビルドが成功すると、[Terminal] (ターミナル) ウィンドウに [ビルドが正常に終了しました] と報告されます。
ロジックアプリプロジェクトに次の項目が存在することを確認します。
- ワークスペースで、次のフォルダーを展開します: LogicApp>lib\custom>net472。 net472 という名前のサブフォルダーに、<関数名>.dll という名前のファイルを含む、コードの実行に必要な複数のアセンブリが含まれていることを確認します。
- ワークスペースで、次のフォルダーを展開します: LogicApp>lib\custom><function-name>。 <function-name> という名前のサブフォルダーに、作成した関数コードに関するメタデータを含む function.json ファイルが含まれていることを確認します。ワークフローデザイナーは、このファイルを使用して、コードの呼び出し時に必要な入力と出力を判断します。
次の例は、ロジックアプリプロジェクトで生成されたアセンブリとその他のファイルの例を示しています。

ワークフローからルールを呼び出す

コードがコンパイルされたこと、およびロジックアプリルールのエンジンプロジェクトにコードの実行に必要なファイルが含まれていることを確認したら、ロジックアプリプロジェクトに含まれている既定のワークフローを開きます。

ワークスペースの [LogicApp] で、<ワークフロー名> ノードを展開し、workflow.json のショートカットメニューを開き、[デザイナーを開く] を選択します。

開いたワークフローデザイナーに、ロジックアプリプロジェクトに含まれる既定のワークフローが、次のトリガーおよびアクションと共に表示されます。
- [HTTP 要求の受信時] という名前の組み込みの要求トリガー
- [このロジックアプリのローカルルール関数を呼び出す] という名前の組み込みアクション
- [応答] という名前の組み込みの応答アクション。要求トリガーを使用するときにのみ呼び出し元に返信する場合に使用します
[このロジックアプリのローカルルール関数を呼び出す] という名前のアクションを選択します。

このアクションの情報ペインが右側に開きます。
[関数名] パラメーターの値が、実行するルール関数に設定されていることを確認します。関数で使用するその他のパラメーター値を確認または変更します。

コードとワークフローをデバッグする

Azurite ストレージエミュレーターを起動するには、次の手順を 3 回 (次の各 Azure Storage サービスに対して 1 回ずつ) 繰り返します。
- Azure BLOB サービス
- Azure Queue サービス
- Azure テーブルサービス
1. Visual Studio Code の [表示] メニューから [コマンドパレット] を選びます。
2. 表示されたプロンプトで、[Azurite: Start Blob Service] (Azurite: BLOB サービスの開始) を見つけて選択します。
3. 表示された作業ディレクトリの一覧から、[LogicApp] を選択します。
4. [Azurite: Start Queue Service] (Azurite: Queue サービスの開始) と [Azurite: Start Table Service] (Azurite: Table サービスの開始) に対して、これらの手順を繰り返します。
画面の下部にある Visual Studio Code タスクバーに 3 つのストレージサービスが実行されていることが示されたら、操作は成功です。次に例を示します。
Visual Studio Code のアクティビティバーで、[Run and Debug] (実行とデバッグ) を選択します。 (キーボード: Ctrl + Shift + D)
[Run and Debug] (実行とデバッグ) の一覧で、[Attach to logic app (LogicApp)] (ロジックアプリ (LogicApp) にアタッチ) を選択し (まだ選択されていない場合)、[再生] (緑色の矢印) を選択します。

[Terminal] (ターミナル) ウィンドウが開き、デバッグプロセスが開始したことを示します。 [Debug Console] (デバッグコンソール) ウィンドウが表示され、デバッグの状態が表示されます。 Visual Studio Code の下部にあるタスクバーがオレンジ色に変わり、.NET デバッガーが読み込まれたことを示します。
[Run and Debug] (実行とデバッグ) の一覧で、[Attach to .NET Functions (Functions)] (.NET Functions (Functions) にアタッチ) を選択し、[再生] (緑色の矢印) を選択します。
ブレークポイントを設定するには、関数定義 (<関数名>.cs) またはワークフロー定義 (workflow.json) で、ブレークポイントが必要な行番号を見つけて、左側の列を選択します。次に例を示します。
ワークフローで要求トリガーを手動で実行するには、ワークフローの [概要] ページを開きます。
1. ロジックアプリプロジェクトから workflow.json ファイルのショートカットメニューを開き、[概要] を選択します。
  
  ワークフローの [概要] ページには、ワークフローを手動で開始する場合のために [トリガーの実行] ボタンが用意されています。 [関数名] の [コールバック URL] の値は、ワークフロー内の要求トリガーによって作成された呼び出し可能なエンドポイントの URL です。この URL に要求を送信して、他のアプリ (他のロジックアプリワークフローなど) からワークフローをトリガーできます。
[概要] ページのツールバーで、[トリガーの実行] を選択します。

ワークフローの実行が開始されると、デバッガーによって最初のブレークポイントがアクティブになります。
[実行] メニューまたはデバッガーのツールバーで、デバッグアクションを選択します。

ワークフローの実行が完了すると、[概要] ページに、完了した実行とその実行に関する基本的な詳細が表示されます。
ワークフロー実行の詳細を確認するには、完了した実行を選択します。または、[実行時間] 列の横にある一覧から [Show run] (実行の表示) を選択します。