조건부 XAML

조건부 XAML은 XAML 마크업에서 ApiInformation.IsApiContractPresent 메서드를 직접 사용할 수 있는 방법을 제공합니다. 뒤에 코드를 작성하지 않고 OS 수준 API 계약의 존재에 따라 속성을 설정할 수 있습니다. 조건문은 런타임에 평가되며, 조건부 XAML 태그가 지정된 요소는 평가 결과가 true이면 구문 분석되고 그렇지 않으면 무시됩니다.

Windows 앱 SDK 2.0부터 IXamlCondition 인터페이스를 구현하여 사용자 고유의 조건을 정의할 수도 있습니다. 사용자 지정 조건을 사용하면 기능 플래그 또는 구성 설정과 같은 앱별 상태에 따라 태그를 포함하거나 제외할 수 있습니다. 자세한 내용은 사용자 지정 조건 만들기를 참조하세요.

조건부 XAML에는 Windows 앱 SDK 앱의 최소 OS 버전인 Windows 10 버전 1809(빌드 17763) 이상이 필요합니다.

사전 요구 사항

• Windows 앱 SDK 프로젝트입니다. 설정 단계는 WinUI 3 프로젝트 만들기 및 실행을 참조하세요.
• 버전 적응형 앱 및 ApiInformation 클래스에 대한 익숙함.

Important

기본 제공 조건부 메서드는 메서드를 사용하며, 이 메서드는 OS에서 제공하는 Windows.*(ApiInformation) API 계약 및 형식이 있는지 확인합니다. WinUI 3은 OS가 아닌 Windows 앱 SDK 통해 앱과 함께 제공되므로 이러한 검사는 WinUI 3() 컨트롤에 적용되지 Microsoft.UI.Xaml.*. 디바이스가 실행되는 Windows 10/11 빌드에 관계없이 앱이 빌드되는 모든 WinUI 3 컨트롤은 런타임에 항상 존재합니다. #if 전처리기 지시문도 여기서는 도움이 되지 않습니다. 전처리기 지시문은 실제로 설치된 OS 또는 Windows 앱 SDK 버전을 기준으로 런타임에 평가되는 것이 아니라, 대상 프레임워크를 기준으로 컴파일 시간에 평가되기 때문입니다. 앱이 실행 중인 Windows 앱 SDK 버전에서 기능을 제어하려면 빌드 시 SDK 버전을 확인하거나 API 호출에서 try/catch를 사용합니다. 자세한 내용은 버전 적응 코드를 참조하세요.

API 계약에 대한 ApiInformation 배경 정보는 버전 적응 앱을 참조하세요.

조건부 네임스페이스

XAML에서 조건부 메서드를 사용하려면 페이지 맨 위에 조건부 XAML 네임스페이스를 선언합니다.

xmlns:myNamespace="schema?conditionalMethod(parameter)"

구분 기호 앞의 ? 콘텐츠는 네임스페이스 또는 스키마입니다. ? 뒤의 내용은 네임스페이스가 true 또는 false로 평가될지를 결정하는 조건부 메서드입니다.

대부분의 경우 스키마는 기본 XAML 네임스페이스입니다.

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

조건부 XAML은 다음 조건부 메서드를 지원합니다.

Method	역
IsApiContractPresent(ContractName, VersionNumber)	IsApiContractNotPresent(ContractName, VersionNumber)
IsTypePresent(ControlType)	IsTypeNotPresent(ControlType)
IsPropertyPresent(ControlType, PropertyName)	IsPropertyNotPresent(ControlType, PropertyName)

앱에서 정의하는 조건을 사용할 수도 있습니다. 자세한 내용은 사용자 지정 조건 만들기를 참조하세요.

메모

최상의 디자인 타임 환경을 위해 IsApiContractPresent 및 IsApiContractNotPresent을 사용합니다. 다른 조건부도 Visual Studio 디자인 환경에서 완전히 지원되지 않습니다.

조건부로 속성 설정

다음은 앱이 Windows 10 버전 1903(2019년 5월 업데이트, 빌드 18362) 이상에서 실행되는 경우에만 텍스트를 TextBlock 표시하는 예제입니다. 이는 Windows 앱 SDK 1809층보다 최신 버전이기 때문에 의미 있는 계약 확인입니다.

먼저 조건부 네임스페이스를 정의합니다.

xmlns:contract8Present="http://schemas.microsoft.com/winfx/2006/xaml/presentation?IsApiContractPresent(Windows.Foundation.UniversalApiContract,8)"

그런 다음 조건부 네임스페이스를 사용하여 속성의 접두사를 지정합니다.

<TextBlock contract8Present:Text="Hello, Conditional XAML"/>

전체 마크업은 다음과 같습니다.

<Page
    x:Class="ConditionalTest.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:contract8Present="http://schemas.microsoft.com/winfx/2006/xaml/presentation?IsApiContractPresent(Windows.Foundation.UniversalApiContract,8)">

    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <TextBlock contract8Present:Text="Hello, Conditional XAML"/>
    </Grid>
</Page>

뒤에 있는 해당 체크 인 코드:

TextBlock textBlock = new TextBlock();

if (ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 8))
{
    textBlock.Text = "Hello, Conditional XAML";
}

메모

계약 이름 매개 변수에 대한 문자열을 사용하더라도 IsApiContractPresent XAML 네임스페이스 선언에 따옴표로 넣지 않습니다.

Windows 앱 SDK에서 지원하는 최소 OS 버전은 1809(UniversalApiContract 버전 7)이므로 7 이하의 계약 버전을 확인하는 것은 Windows 앱 SDK 앱에서는 항상 true로 평가되며 유용한 정보를 제공하지 않습니다. 7보다 높은 계약 버전만 확인합니다.

if/else 조건 사용

API 계약에 따라 다른 값을 설정하려면 양수 및 음수 조건부 네임스페이스를 모두 정의합니다.

xmlns:contract8NotPresent="http://schemas.microsoft.com/winfx/2006/xaml/presentation?IsApiContractNotPresent(Windows.Foundation.UniversalApiContract,8)"
xmlns:contract8Present="http://schemas.microsoft.com/winfx/2006/xaml/presentation?IsApiContractPresent(Windows.Foundation.UniversalApiContract,8)"

그런 다음, 각각 다른 조건부 접두사를 사용하여 속성을 두 번 설정합니다. 런타임에 하나만 적용됩니다.

<TextBlock contract8NotPresent:Text="Hello, World"
           contract8Present:Text="Hello, May 2019 Update or later"/>

조건부로 컨트롤 인스턴스화

메모

조건부 속성 설정과 달리 OS API 계약을 기반으로 요소를 조건부로 인스턴스화하는 것은 UWP 관련 패턴입니다. WinUI 3 컨트롤에는 적용되지 않습니다.

UWP에서 이 패턴을 사용하면 OS에서 최신 컨트롤을 사용할 수 없을 때 이전 Windows.UI.Xaml.Controls 컨트롤로 돌아갈 수 있습니다. Windows 앱 SDK 앱에서 WinUI 3 컨트롤(Microsoft.UI.Xaml.Controls.*)은 OS가 아닌 Windows 앱 SDK 통해 앱과 함께 제공됩니다. 앱이 빌드되는 모든 컨트롤(예: 포함 ColorPicker )은 런타임에 존재하도록 보장되므로 인스턴스화하기 전에 확인할 OS 버전이 없습니다.

앱이 대상으로 하는 Windows 앱 SDK 버전을 기준으로 WinUI 3 컨트롤이나 API의 사용 가능 여부를 제한해야 하는 경우, 빌드할 때(최소 Windows 앱 SDK 패키지 버전을 대상으로 지정하여) 확인하거나 런타임 호출을 try/catch로 감싸고, 조건부 XAML은 사용하지 마세요.

기능 플래그와 같이 앱이 정의하는 논리에 따라 요소를 포함하거나 제외하려면 사용자 지정 조건을 사용합니다.

사용자 지정 조건 만들기

Windows 앱 SDK 2.0부터 고유한 조건을 정의하고 조건부 네임스페이스 구문과 함께 사용할 수 있습니다. 사용자 지정 조건을 사용하면 기능 플래그, 구성 설정 또는 디바이스 기능과 같은 앱별 상태에 따라 태그를 포함하거나 제외할 수 있습니다. 기본 제공 조건부 메서드와 마찬가지로 사용자 지정 조건은 런타임에 XAML을 구문 분석할 때 평가됩니다.

• 중요 API: IXamlCondition 인터페이스, IXamlCondition.Evaluate 메서드

WinUI 3 갤러리 앱을 열고 사용자 지정 XAML 조건부가 실제로 어떻게 작동하는지 확인합니다

WinUI 3 갤러리 앱에는 WinUI 컨트롤 및 기능의 대화형 예제가 포함되어 있습니다. Microsoft Store에서 앱을 다운로드하거나 GitHub 소스 코드를 찾습니다.

메모

IXamlCondition는 Windows 앱 SDK 2.0의 실험적 릴리스에 있던 IXamlPredicate 인터페이스를 대체합니다.

조건 설정

조건을 만들려면 DependencyObject에서 파생되고 IXamlCondition를 구현하는 클래스를 정의합니다. XAML 파서는 Evaluate 메서드를 호출하고 조건부 네임스페이스 선언의 괄호 사이의 텍스트를 argument 매개 변수로 전달합니다. 정규화된 태그를 포함하려면 false을 반환하고, 이를 무시하려면 true을 반환합니다.

이 예제는 WinUI 3 갤러리 샘플에서 앱이 사전에 저장된 기능 플래그를 확인합니다.

using System.Collections.Generic;
using Microsoft.UI.Xaml;
using Microsoft.UI.Xaml.Markup;

namespace MyApp;

public sealed partial class FeatureFlagCondition : DependencyObject, IXamlCondition
{
    public static IDictionary<string, bool> FeatureFlags { get; } = new Dictionary<string, bool>
    {
        ["NewExperience"] = true,
        ["LegacyMode"] = false,
    };

    // The XAML parser calls Evaluate with the text between the parentheses
    // in the conditional namespace declaration, for example "NewExperience".
    public bool Evaluate(string argument)
    {
        return FeatureFlags.TryGetValue(argument, out bool enabled) && enabled;
    }
}

조건에 대한 조건부 네임스페이스 선언

먼저 using: 선언을 사용하여 조건 클래스가 포함된 네임스페이스를 매핑합니다. 그런 다음 조건부 네임스페이스의 ? 구분 기호 뒤에 해당 접두사를 통해 클래스를 참조하고 인수를 괄호 안에 전달합니다:

xmlns:cond="using:MyApp"
xmlns:newExp="http://schemas.microsoft.com/winfx/2006/xaml/presentation?cond:FeatureFlagCondition(NewExperience)"
xmlns:legacy="http://schemas.microsoft.com/winfx/2006/xaml/presentation?cond:FeatureFlagCondition(LegacyMode)"

이 예제에서 파서는 Evaluate("LegacyMode") 접두사를 사용하는 마크업에 대해 newExp를 호출하고, Evaluate("NewExperience") 접두사를 사용하는 마크업에 대해 legacy를 호출합니다.

요소, 속성 및 setter에 조건 사용

기본 제공 조건부 네임스페이스를 사용하는 것과 동일한 방식으로 조건부 접두사를 사용합니다. 이러한 예제는 WinUI 3 갤러리 샘플을 기반으로 합니다.

조건이 true있는 경우에만 요소를 포함하려면 요소 앞에 접두사를 붙입니다.

<StackPanel Spacing="8">
    <!-- Included only when FeatureFlagCondition.Evaluate("NewExperience") returns true. -->
    <newExp:InfoBar Title="New experience" IsOpen="True" Severity="Success"
                    Message="This InfoBar is included because the NewExperience flag is true." />

    <!-- Included only when FeatureFlagCondition.Evaluate("LegacyMode") returns true. -->
    <legacy:InfoBar Title="Legacy mode" IsOpen="True" Severity="Warning"
                    Message="This InfoBar is included because the LegacyMode flag is true." />
</StackPanel>

조건이 true일 때만 속성을 설정하려면 특성 앞에 접두사를 붙입니다.

<!-- Make sure that no more than one of these conditions is true at runtime. -->
<Button newExp:Content="Open the new editor"
        legacy:Content="Open the classic editor" />

조건이 true일 때만 스타일 setter를 적용하려면 Setter 요소 앞에 접두사를 붙입니다:

<Page.Resources>
    <Style x:Key="ConditionalHeadingStyle" TargetType="TextBlock">
        <newExp:Setter Property="FontWeight" Value="SemiBold" />
        <newExp:Setter Property="FontSize" Value="28" />
        <legacy:Setter Property="FontWeight" Value="Normal" />
        <legacy:Setter Property="FontSize" Value="18" />
    </Style>
</Page.Resources>

XAML을 구문 분석하기 전에 상태 설정

파서는 프로세스의 Evaluate 수명 동안 조건과 인수의 각 조합에 대한 결과를 캐시합니다. 결과가 캐시된 후 조건이 읽는 상태를 변경하는 경우 이미 구문 분석된 태그는 변경되지 않으며 나중에 구문 분석된 태그는 캐시된 결과를 계속 사용합니다. 다른 값을 사용하려면 앱을 다시 시작하세요.

예를 들어 앱 시작 시 또는 페이지 생성자에서 InitializeComponent를 호출하기 전에, 파서가 조건을 평가하기 전에 조건이 읽는 상태를 설정합니다.

public sealed partial class MainPage : Page
{
    public MainPage()
    {
        // Set the flags before InitializeComponent so that the XAML parser
        // uses these values when it evaluates the conditions.
        FeatureFlagCondition.FeatureFlags["NewExperience"] = true;
        FeatureFlagCondition.FeatureFlags["LegacyMode"] = false;

        this.InitializeComponent();
    }
}

Limitations

• 런타임에 두 요소 중 하나만 포함되더라도 두 요소는 같은 x:Name를 가질 수 없습니다.
• 동일한 특성에 둘 이상의 조건을 적용하는 경우 해당 조건 중 하나만 런타임에 true로 평가되는지 확인합니다. 둘 이상의 값의 결과가 true이면 파서가 예외를 발생시킵니다.
• 런타임 시 조건이 평가되므로 XAML 컴파일러에서 논리적 일관성을 확인할 수 없습니다. 앱에서 지원하는 조건 값의 각 조합을 테스트합니다.
• 사용자 지정 조건은 http://schemas.microsoft.com/winfx/2006/xaml 네임스페이스(x:Uid)의 항목(예: x:Key 및 x:)에는 작동하지 않습니다.

관련 콘텐츠

• 버전 적응 앱
• 버전 적응 코드
• IXamlCondition 인터페이스