Share via

범용 FetchXML로 Universal Resource Scheduling 확장

  • 아티클

UFX는 동적 FetchXML을 사용하여 데이터를 쿼리하고, Universal Resource Scheduling(URS) 솔루션에 의한 소비에 대한 결과 데이터를 만들고 준비할 수 있는 고급 쿼리 언어입니다. 이 쿼리 언어를 사용하면 사용자 지정 쿼리를 만들어 일정 게시판을 사용자 지정 및 확장하고 조직의 고유한 비즈니스 요구 사항에 맞게 도우미 필터를 예약할 수 있습니다.

UFX는 UFX 모음과 UFX 쿼리 두 구성 요소로 구성되어 있습니다.

간단한 UFX 모음

UFX 모음은 정적 형식의 데이터를 포함합니다. 메모리에서는 키와 값이 있는 사전으로 표시됩니다. JSON 및 XML로 직렬화할 수 있습니다. 데이터를 형식화하면 UFX 쿼리에서 데이터를 쿼리하고 클라이언트 UI에서 바인딩할 수 있습니다.

실용성과 성능상의 이유로 메모리 내 모음은 Dynamics 365 앱 SDK Entity 개체의 상단에 구현됩니다.

샘플 모음에는 두 값이 포함되어 있습니다.

메모리 내:

키 값 유형
이름 John 문자열
연령 36 int

JSON:

{
    "name": "John",
    "age": 36
}

XML:

<bag>
    <name ufx-type="string">John</name>
    <age ufx-type="int">36</age>
</bag>

UFX 지원 형식

UFX 모음은 많은 유형의 값을 포함할 수 있습니다. 세 가지 유형 클래스로 분류됩니다.

카테고리 값
간단한 유형 bool (Boolean), int (Int32), long (Int64), double (Double), decimal (Decimal), datetime (DateTime), guid (Guid), string (String)
Dynamics 365에 특정한 간단한 유형: money (Money), option (OptionSet), lookup (EntityReference)
기타 모음 bag (Entity)
모음 목록 list (EntityCollection)

다음은 더 많은 유형이 포함된 샘플 JSON 모음입니다.

{
    "citizen": true,          // implicit bool
    
    "age": 36,                // explicit int
    "age@ufx-type": "int",

    "name": {                 // nested bag
        "first": "John",
        "last": "Doe"
    },

    "children": [             // list of bags
        { "name": "Sam" },
        { "name": "Judy" }
    ]
}

XML의 모음과 동일:

<bag>
    <citizen ufx-type="bool">true</citizen>

    <age ufx-type="int">36</age>

    <name ufx-type="bag">
        <first ufx-type="string">John</first>
        <last ufx-type="string">Doe</last>
    </name>

    <children ufx-type="list">
        <bag>
            <name ufx-type="string">Sam</name>
        </bag>
        <bag>
            <name ufx-type="string">Judy</name>
        </bag>
    </children>
</bag>

UFX 쿼리 소개

UFX 쿼리는 XML 기반 UFX 모음으로 작성됩니다. 모음의 속성은 동적으로 데이터를 쿼리하는 UFX 지시문을 포함할 수 있습니다. UFX 쿼리는 XML이 아닌 메모리 내 개체에서 실행됩니다. 지시문만 XML로 작성됩니다. 출력은 JSON 또는 XML로 직렬화할 수 있습니다.

다음 UFX 쿼리는 source UFX 지시문을 사용하여 모음에 accounts 속성을 정의합니다. 이로 인해 인라인 FetchXML이 Dynamics 365에서 실행되고 accounts 속성은 모음 목록이 되거나 각 모음이 Dynamics 365에서 거래처 레코드의 인스턴스인 EntityCollection이 됩니다.

<bag xmlns:ufx="https://schemas.microsoft.com/dynamics/2017/universalfetchxml">
    <accounts ufx:source="fetch">
        <fetch top="10">
            <entity name="account" />
        </fetch>
    </accounts>
</bag>

UFX 쿼리는 순차적으로 처리되며 많은 FetchXML 쿼리를 포함할 수 있습니다.

다음은 XML로 직렬화된 이전 UFX 쿼리의 결과 코드 조각입니다. 일부 값에는 추가로 설명을 제공하는 메타데이터가 있습니다.

<bag>
  <accounts ufx-type="list">
    <bag ufx-id="166e39dd-34a1-e611-8111-00155d652f01" ufx-logicalname="account">
      <accountid ufx-type="guid">166e39dd-34a1-e611-8111-00155d652f01</accountid>
      <accountnumber ufx-type="string">ABSS4G45</accountnumber>
      <name ufx-type="string">Fourth Coffee (sample)</name>
      <statecode ufx-type="option" ufx-formatvalue="Active">0</statecode>
      <websiteurl ufx-type="string">https://www.fourthcoffee.com/</websiteurl>
      <primarycontactid ufx-type="lookup" ufx-formatvalue="Yvonne McKay (sample)" ufx-logicalname="contact">7c6e39dd-34a1-e611-8111-00155d652f01</primarycontactid>
      ...
    </bag>
    <bag ufx-type="bag" ufx-id="186e39dd-34a1-e611-8111-00155d652f01" ufx-logicalname="account">
      <accountid ufx-type="guid">186e39dd-34a1-e611-8111-00155d652f01</accountid>
      <accountnumber ufx-type="string">ACTBBDC3</accountnumber>
      <name ufx-type="string">Litware, Inc. (sample)</name>
      <statecode ufx-type="option" ufx-formatvalue="Active">0</statecode>
      <websiteurl ufx-type="string">https://www.litwareinc.com/</websiteurl>
      <primarycontactid ufx-type="lookup" ufx-formatvalue="Susanna Stubberod (sample)" ufx-logicalname="contact">7e6e39dd-34a1-e611-8111-00155d652f01</primarycontactid>
      ...
    </bag>
    ...
  </accounts>
</bag>

select UFX 지시문은 현재 모음에서 값을 선택하는 XPath 표현식을 사용합합니다.

<bag xmlns:ufx="https://schemas.microsoft.com/dynamics/2017/universalfetchxml">
    <accounts ufx:source="fetch">
        <fetch top="10">
            <entity name="account" />
        </fetch>
    </accounts>

    <first_account_name ufx:select="accounts/bag[1]/name" />

    <!-- null values remove properties from the bag -->
    <accounts ufx:select="$null" />
</bag>

XML의 결과 모음:

<bag>
    <first_account_name ufx-type="string">Fourth Coffee (sample)</first_acount_name>
</bag>

확실히 UFX 쿼리의 가장 강력한 측면은 입력 데이터를 기반으로 FetchXML을 동적으로 생성하는 기능입니다.

아래 샘플에서는 사용자가 제공한 값으로 거래처를 검색하고 XPath $input 변수를 통해 UFX 모음으로 사용할 수 있습니다. condition 요소에서 UFX if 및 value 지시문을 확인하십시오.

<bag xmlns:ufx="https://schemas.microsoft.com/dynamics/2017/universalfetchxml">
    <accounts ufx:source="fetch">
        <fetch top="10">
            <entity name="account">
                <filter>
                    <condition attribute="name" operator="like" ufx:if="$input/NameFilter">
                        <ufx:value select="$input/NameFilter" attribute="value" />
                    </condition>
                </filter>
            </entity>
        </fetch>
    </accounts>
</bag>

입력 모음의 NameFilter 속성에 %city%이(가) 포함된 경우 Dynamics 365에서 실행하여 생성된 FetchXML 조건은 다음과 같아 보일 것입니다.

<condition attribute="name" operator="like" value="%city%" />

키, 값 및 메타데이터

UFX 모음에는 키와 값이 포함되어 있으며 일부 값은 자세한 설명을 제공하는 추가 메타데이터가 있습니다.

lookup (EntityReference) 형식의 값을 예로 들 수 있습니다. FetchXML을 통해 Dynamics 365에서 쿼리할 때 레코드의 서식이 지정된 표시 이름 뿐만 아니라 엔터티의 논리적 이름을 반환합니다. UFX 모음은 기본 값에 연결된 메타데이터로 이러한 추가 정보를 제공합니다.

JSON으로 직렬화된 lookup : 메타데이터는 다음과 같습니다.

{
    "primarycontactid": "7e6e39dd-34a1-e611-8111-00155d652f01",
    "primarycontactid@ufx-type": "lookup",
    "primarycontactid@ufx-logicalname": "contact",
    "primarycontactid@ufx-formatvalue": "Susanna Stubberod (sample)"
}

XML:

<primarycontactid ufx-type="lookup" ufx-formatvalue="Susanna Stubberod (sample)" ufx-logicalname="contact">7e6e39dd-34a1-e611-8111-00155d652f01</primarycontactid>

Dynamics 365 데이터에 대한 XPath

UFX 모음에 입력된 데이터를 사용하면 UFX 쿼리가 구조화된 형식으로 이를 표시하고 XPath를 사용하여 데이터를 탐색하고 값을 선택할 수 있습니다.

UFX 지시문에 지정 된 XPath 표현식은 모음의 데이터를 XML 직렬화 형식의 모음 구조와 유사하게 표시합니다. 그러나 데이터는 XML 문서가 아닌 메모리 내 .NET 개체(Entity 및 EntityCollection 형식의 인스턴스)에 저장됩니다.

부록 A: UFX 형식 참조

참고: 모든 UFX 유형은 ufx-type 및 ufx-formatvalue 메타데이터를 지원합니다. 추가 메타데이터는 아래 표에서 각 형식 옆에 설명되어 있습니다.

UFX 이름 특성 유형 코드 .NET 이름 UFX 메타데이터
bool Boolean Boolean
int 정수 Int32
long BigInt Int64
double Double Double
10진수 소수 소수
datetime 날짜 시간 날짜 시간
guid Uniqueidentifier Guid
문자열 메모 문자열
money 통화 통화
옵션 Picklist OptionSetValue
조회 조회 EntityReference ufx-logicalname
모음 해당 없음 엔터티 ufx-id
ufx-logicalname
목록 해당 없음 EntityCollection
해당 없음 해당 없음 AliasedValue ufx-aliasentity
ufx-aliasattribute

부록 B: UFX 쿼리 지시문

UFX 지시문은 모음 속성 및 FetchXML 쿼리의 XML 요소에 사용할 수 있습니다.

UFX 모음 지시문

Attribute(특성) Value 설명
ufx:if XPath XPath 표현식을 테스트하고 테스트가 true를 반환하는 경우에만 속성을 처리합니다.
ufx:source fetch 인라인 <fetch> XML 요소를 실행하고 속성에 결과를 할당합니다.
ufx:select XPath XPath 표현식을 실행하고 속성에 결과를 할당합니다.
XML 형식의 bag 또는 list 선택적 하위 bag을 쿼리할 때 XPath 표현식의 결과를 변환하도록 지정할 수 있습니다.

UFX FetchXML 지시문

Element(요소) Attribute(특성) Value 설명
모든 요소 ufx:if XPath XPath 표현식을 테스트하고 테스트가 성공한 경우에만 XML 요소를 내보냅니다.
ufx:apply select XPath XPath 표현식에서 반환되는 nodeset을 반복하고 각 노드에 대해 하위 XML 요소를 한 번 출력합니다.
ufx:value select XPath XPath 표현식을 실행하고 현재 XML 요소에 결과를 출력합니다.
ufx:value attribute 특성 이름 XPath 표현식 결과를 현재 XML 요소에 지정된 특성 이름에 할당합니다.

부록 C: UFX XPath 함수

UFX는 XPath에서 기본적으로 사용할 수 있는 것 외에도 여러 가지 새로운 기능을 추가합니다.

datetime()

  • datetime(): 현재 시간을 UTC로 반환합니다.

list()

  • list(bag | list, ...[bag | list]): 많은 bag 또는 list 값을 입력으로 받아 단일 list으로 줄입니다.

lookup-to-list()

  • lookup-to-list(lookup, ...[lookup]): 많은 lookup 값을 받아 각 값을 ufx-id 및 ufx-logicalname 메타데이터 집합이 있는 bag으로 변환하고 단일 list으로 줄입니다.

option-to-list()

  • option-to-list(option, ...[option]): 많은 option 값을 받아 각 값을 단일 option 속성이 있는 bag으로 변환하고 단일 list으로 줄입니다.

order()

  • order(list, string, bool): 각 모음에서 속성으로 목록을 정렬합니다. 이 속성은 인수 2에 지정되며, 내림차순은 인수 3에 지정됩니다.
  • order(list, list): 인수 2의 목록으로 지정된 여러 정렬 순서로 목록으로 정렬합니다. 두 번째 목록의 각 bag은 name 및 descending 속성을 가질 수 있습니다.

iif()

  • iif(any, any, any): 인수 1이 true이면 인수 2를 반환하고 그렇지 않으면 인수 3을 반환합니다.

부록 D: UFX XPath 변수

이름 설명
$input bag을 입력 값이 있는 UFX 쿼리에 사용할 수 있습니다.
$null Null 상수입니다. 속성에서 $null을 선택하면 모음에서 속성을 제거합니다.
$current UFX 쿼리에서 처리 중인 현재 모음에 대한 참조

참조

Universal Resource Scheduling에서 리소스 일치 이해 및 사용자 정의

Universal Resource Scheduling 확장성 릴리스 노트