Koşullu XAML

Koşullu XAML , ApiInformation.IsApiContractPresent yöntemini doğrudan XAML işaretlemesinde kullanmak için bir yol sağlar. Arkasında kod yazmadan işletim sistemi düzeyi API sözleşmesinin varlığına göre özellikleri ayarlayabilirsiniz. Koşullu ifadeler çalışma zamanında değerlendirilir; koşullu XAML etiketiyle nitelenen öğeler, değerlendirme sonucu true olursa ayrıştırılır, aksi takdirde yok sayılır.

Windows Uygulama SDK'sı 2.0'dan başlayarak, IXamlCondition arabirimini uygulayarak kendi koşullarınızı da tanımlayabilirsiniz. Özel koşullar, özellik bayrakları veya yapılandırma ayarları gibi uygulamaya özgü duruma göre işaretleme eklemenize veya hariç tutmanıza olanak tanır. Daha fazla bilgi için bkz. Özel koşullar oluşturma.

Koşullu XAML, Windows Uygulama SDK'sı uygulamaları için en düşük işletim sistemi sürümü olan Windows 10 sürüm 1809 (derleme 17763) veya sonraki bir sürümü gerektirir.

Prerequisites

bir Windows Uygulama SDK'sı projesi. Kurulum adımları için bkz. WinUI 3 projesi oluşturma ve çalıştırma.
Sürüm uyarlamalı uygulamalara ve ApiInformation sınıfına aşinalık.

Important

Yerleşik koşullu yöntemler, işletim sistemi tarafından sağlanan Windows.* (ApiInformation) API sözleşmelerinin ve türlerinin var olup olmadığını denetleyen yöntemini kullanır. Bu denetimler WinUI 3 () denetimleri için geçerli Microsoft.UI.Xaml.* çünkü WinUI 3, uygulamanızı işletim sistemi yerine Windows Uygulama SDK'sı üzerinden gönderir; uygulamanızın derlendiği her WinUI 3 denetimi, cihazın hangi Windows 10/11 derlemesinin çalıştığına bakılmaksızın her zaman çalışma zamanında bulunur. #if Önişlemci yönergeleri burada da işe yaramaz: bunlar, çalışma zamanında fiilen yüklü olan işletim sistemine veya Windows Uygulama SDK'sı sürümüne göre değil, derleme zamanında hedef çerçeveye göre değerlendirilir. Bir özelliği, uygulamanızın çalıştığı Windows Uygulama SDK'sı sürümüne göre kullanılabilir duruma getirmek için, derleme zamanında SDK sürümünü denetleyin veya API çağrısını bir try/catch bloğu içine alın. Ayrıntılar için bkz . Sürüm uyarlamalı kodu .

ApiInformation ve API sözleşmeleri hakkında arka plan bilgileri için Sürüm uyarlamalı uygulamalar bölümüne bakın.

Koşullu ad alanları

XAML'de koşullu bir yöntem kullanmak için sayfanızın üst kısmında bir koşullu XAML ad alanı bildirin:

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

Sınırlayıcıdan ? önceki içerik ad alanı veya şemadır. ? etiketinden sonraki içerik, ad alanının true mi yoksa false mi olarak değerlendirileceğini belirleyen koşullu yöntemdir.

Çoğu durumda şema varsayılan XAML ad alanıdır:

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

Koşullu XAML şu koşullu yöntemleri destekler:

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

Uygulamanızda tanımladığınız bir koşulu da kullanabilirsiniz. Daha fazla bilgi için bkz. Özel koşullar oluşturma.

Note

En iyi tasarım zamanı deneyimi için IsApiContractPresent ve IsApiContractNotPresent kullanın. Diğer koşullular, Visual Studio tasarım deneyiminde tam olarak desteklenmez.

Bir özelliği koşullu olarak ayarlama

Bu örnek, uygulama yalnızca Windows 10 sürüm 1903'te (Mayıs 2019 Güncelleştirmesi, derleme 18362) veya daha sonraki bir sürümde çalıştığında TextBlock içinde metin görüntüler; bu API sözleşmesi denetimi anlamlıdır çünkü Windows Uygulama SDK'sı'nın 1809 taban sürümünden daha yenidir.

İlk olarak, bir koşullu ad alanı tanımlayın:

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

Ardından özelliğine koşullu ad alanı ön eki ekleyin:

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

Tam işaretleme aşağıdadır:

<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>

Arka planda eşdeğer iade kodu:

TextBlock textBlock = new TextBlock();

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

Note

IsApiContractPresent, sözleşme adı parametresi için bir dize almasına rağmen, onu XAML ad alanı bildiriminde tırnak içine almazsınız.

Windows Uygulama SDK'sı’sinin desteklediği en düşük işletim sistemi sürümü 1809 (UniversalApiContract sürüm 7) olduğundan, 7 veya daha düşük bir sözleşme sürümünün denetlenmesi Windows Uygulama SDK'sı uygulamasında her zaman true sonucunu verir ve yararlı bir bilgi sağlamaz. Yalnızca 7'den yüksek sözleşme sürümlerini denetleyin.

If/else koşullarını kullanma

API sözleşmesine bağlı olarak farklı değerler ayarlamak için hem pozitif hem de negatif koşullu ad alanlarını tanımlayın:

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)"

Ardından, her birinin farklı bir koşullu ön eki olan özelliğini iki kez ayarlayın. Çalışma zamanında yalnızca bir tane uygulanır:

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

Denetimleri koşullu olarak oluşturma

Note

Bir öğeyi, bir özelliği koşullu olarak ayarlamak yerine işletim sistemi API sözleşmesine bağlı olarak koşullu biçimde örneklendirmek, UWP'ye özgü bir desendir. WinUI 3 denetimleri için geçerli değildir.

UWP'de bu düzen, işletim sisteminde daha yeni bir tane kullanılamadığında daha eski Windows.UI.Xaml.Controls bir denetime geri dönmenizi sağlar. Windows Uygulama SDK'sı kullanan bir uygulamada, WinUI 3 denetimleri (Microsoft.UI.Xaml.Controls.*) işletim sistemiyle değil, Windows Uygulama SDK'sı aracılığıyla uygulamanızla birlikte gelir. Uygulamanızın hedef alarak derlendiği her denetimin — ColorPicker dahil — çalışma zamanında mevcut olması garanti edilir; bu nedenle örneğini oluşturmadan önce kontrol etmeniz gereken bir işletim sistemi sürümü yoktur.

Uygulamanızın hedeflediği Windows Uygulama SDK'sı sürümüne göre bir WinUI 3 denetiminin veya API’sinin kullanımını koşullandırmanız gerekiyorsa, bu denetlemeyi derleme zamanında yapın (minimum bir Windows Uygulama SDK'sı paket sürümünü hedefleyerek) ya da çalışma zamanı çağrısını try/catch içine sarın — koşullu XAML ile değil.

Özellik bayrağı gibi uygulamanızın tanımladığı mantığa dayalı öğeleri dahil etmek veya dışlamak için özel bir koşul kullanın.

Özel koşullar oluştur

Windows Uygulama SDK'sı 2.0'dan başlayarak, kendi koşullarınızı tanımlayabilir ve bunları koşullu ad alanı söz dizimi ile kullanabilirsiniz. Özel koşul, özellik bayrakları, yapılandırma ayarları veya cihaz özellikleri gibi uygulamaya özgü duruma göre işaretleme eklemenize veya kaldırmanıza olanak tanır. Yerleşik koşullu yöntemler gibi, özel koşullar da XAML çalışma zamanında ayrıştırıldığında değerlendirilir.

Önemli API'ler: IXamlCondition arabirimi, IXamlCondition.Evaluate yöntemi

WinUI 3 Galeri uygulamasını açın ve özel XAML koşullularının çalıştığını görün

WinUI 3 Galeri uygulaması, WinUI denetimlerinin ve özelliklerinin etkileşimli örneklerini içerir. uygulamayı Microsoft Store adresinden alın veya GitHub üzerindeki kaynak koduna göz atın.

Note

IXamlCondition, Windows Uygulama SDK'sı 2.0'ın deneysel sürümlerindeki IXamlPredicate arabiriminin yerini alır.

Bir koşul uygulayın

Bir koşul oluşturmak için, DependencyObject'ten türeyen ve IXamlCondition uygulayan bir sınıf tanımlayın. XAML ayrıştırıcısı Evaluate yöntemini çağırır ve koşullu ad alanı bildirimindeki parantezler arasındaki metni argument parametresi olarak geçirir. false uygun işaretlemeyi eklemek için veya true bunu yoksaymak için geri dönün.

WinUI 3 Galerisi örneğinden alınan bu örnek, uygulamanın bir sözlükte depoladığı özellik bayraklarını değerlendirir:

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;
    }
}

Koşul için koşullu ad alanı tanımlayın

İlk olarak, bir using: bildirim kullanarak koşul sınıfınızı içeren ad alanını eşleyin. Ardından, koşullu ad alanının ? ayırıcısından sonra, sınıfa bu önek üzerinden başvurun ve bağımsız değişkeni parantez içinde geçirin:

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)"

Bu örnekte ayrıştırıcı, Evaluate("LegacyMode") önekini kullanan işaretleme için newExp ve Evaluate("NewExperience") önekini kullanan işaretleme için legacy çağırır.

Koşulu öğeler, öznitelikler ve ayarlayıcılar üzerinde kullanmak

Koşullu ön eki, yerleşik koşullu ad alanlarını kullandığınız gibi kullanın. Bu örnekler WinUI 3 Galerisi örneğini temel alır.

Bir öğeyi yalnızca bir koşul true olduğunda eklemek için öğenin başına bir önek getirin:

<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>

Bir özelliği yalnızca koşul true olduğunda ayarlamak için özniteliğine ön ek ekleyin:

<!-- 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" />

Bir stil ayarlayıcısını yalnızca bir koşul true olduğunda uygulamak için Setter öğesine önek ekleyin:

<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 ayrıştırılmadan önce durumu ayarlayın

Ayrıştırıcı, işlemin ömrü boyunca koşul ve bağımsız değişkenin her birleşimi için Evaluate sonucunu önbelleğe alır. Sonuç önbelleğe alındıktan sonra koşulun okuduğu durumu değiştirirseniz, zaten ayrıştırılmış olan işaretleme değişmez ve daha sonra ayrıştırılan işaretleme yine de önbelleğe alınmış sonucu kullanır. Farklı bir değer kullanmak için uygulamayı yeniden başlatın.

Ayrıştırıcı bunu değerlendirmeden önce, örneğin uygulama başlangıcında veya bir sayfa oluşturucusunda InitializeComponent çağırmadan önce koşulunuzun okuduğu durumu ayarlayın:

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

Çalışma zamanında bunlardan yalnızca biri dahil edilse bile, iki öğe aynı x:Name değerine sahip olamaz.
Aynı özniteliğe birden fazla koşul uygularsanız, bunların yalnızca birinin çalışma zamanında true olarak değerlendirildiğinden emin olun. Birden fazlası true olarak değerlendirilirse, ayrıştırıcı bir özel durum oluşturur.
Koşullar çalışma zamanında değerlendirildiğinden, XAML derleyicisi bunları mantıksal tutarlılık açısından denetleyemez. Uygulamanızın desteklediği koşul değerlerinin her birleşimini test edin.
Özel koşullar, x:Uid ad alanındaki (x:Key) http://schemas.microsoft.com/winfx/2006/xaml ve x: gibi öğelerle çalışmaz.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Son güncelleştirme: 2026-10-15

Koşullu XAML

Prerequisites

Koşullu ad alanları

Bir özelliği koşullu olarak ayarlama

If/else koşullarını kullanma

Denetimleri koşullu olarak oluşturma

Özel koşullar oluştur

Bir koşul uygulayın

Koşul için koşullu ad alanı tanımlayın

Koşulu öğeler, öznitelikler ve ayarlayıcılar üzerinde kullanmak

XAML ayrıştırılmadan önce durumu ayarlayın

Limitations

İlgili içerik

Geri Bildirim

Ek kaynaklar