범용 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-idufx-logicalname |
| 목록 | 해당 없음 | EntityCollection | |
| 해당 없음 | 해당 없음 | AliasedValue | ufx-aliasentityufx-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 쿼리에서 처리 중인 현재 모음에 대한 참조 |