Skip to content

samples: update ACI samples for capability coupling rules #593

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
surajkumar-08 wants to merge 6 commits into
base: main
Choose a base branch
from
Draft

samples: update ACI samples for capability coupling rules #593

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
214c172
samples: update ACI samples for capability coupling rules
surakumar_microsoft Mar 12, 2026
291d1c4
Merge remote-tracking branch 'upstream/main' into update-aci-api-changes
Apr 22, 2026
694805b
enhance: Update AppIndexCapability and SemanticSearch to demonstrate …
Apr 23, 2026
7af8ac7
refactor: Simplify index capability suppression logic and improve err…
Apr 27, 2026
02ef8a7
fix: Change index deletion behavior to defer if in use for capability…
Apr 28, 2026
15a67f8
fix: Correct typo in vegetable stew description in SemanticSearch
Apr 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 78 additions & 65 deletions AIDevGallery/Samples/WCRAPIs/AppIndexCapability.xaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,71 +8,84 @@
xmlns:samples="using:AIDevGallery.Samples"
mc:Ignorable="d">

<Grid>
<Grid.RowDefinitions>
<RowDefinition Height="Auto" />
<RowDefinition Height="*" />
</Grid.RowDefinitions>
<StackPanel Spacing="8">
<TextBlock Style="{StaticResource CaptionTextBlockStyle}" Foreground="{ThemeResource TextFillColorSecondaryBrush}" Text="Index Capabilities of Current System:" />
<StackPanel>
<!-- Lexical Text Capability Status -->
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowLightCardStyle}">
<TextBlock Grid.Column="0" Text="Lexical Text Capability Status:"/>
<TextBlock Grid.Column="1" x:Name="lexicalCapabilityResultText"/>
</Grid>
<!-- Semantic Text Capability Status -->
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowCardStyle}">
<TextBlock Grid.Column="0" Text="Semantic Text Capability Status:"/>
<TextBlock Grid.Column="1" x:Name="semanticCapabilityResultText"/>
</Grid>
<!-- OCR Capability Status -->
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowLightCardStyle}">
<TextBlock Grid.Column="0" Text="OCR Capability Status:"/>
<TextBlock Grid.Column="1" x:Name="oCRCapabilityResultText"/>
</Grid>
<!-- Semantic Image Capability Status -->
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowCardStyle}">
<TextBlock Grid.Column="0" Text="Semantic Image Capability Status:"/>
<TextBlock Grid.Column="1" x:Name="semanticImageCapabilityResultText"/>
</Grid>
</StackPanel>
<ScrollViewer VerticalScrollBarVisibility="Auto">
<Grid Padding="0,0,0,20">
<StackPanel Spacing="16">
<!-- System Capabilities Section -->
<TextBlock Style="{StaticResource CaptionTextBlockStyle}" Foreground="{ThemeResource TextFillColorSecondaryBrush}" Text="Index Capabilities of Current System:" />
<StackPanel>
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowLightCardStyle}">
<TextBlock Grid.Column="0" Text="Lexical Text Capability Status:"/>
<TextBlock Grid.Column="1" x:Name="lexicalCapabilityResultText"/>
</Grid>
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowCardStyle}">
<TextBlock Grid.Column="0" Text="Semantic Text Capability Status:"/>
<TextBlock Grid.Column="1" x:Name="semanticCapabilityResultText"/>
</Grid>
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowLightCardStyle}">
<TextBlock Grid.Column="0" Text="OCR Capability Status:"/>
<TextBlock Grid.Column="1" x:Name="oCRCapabilityResultText"/>
</Grid>
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowCardStyle}">
<TextBlock Grid.Column="0" Text="Semantic Image Capability Status:"/>
<TextBlock Grid.Column="1" x:Name="semanticImageCapabilityResultText"/>
</Grid>
</StackPanel>

<!-- Index Instance Capabilities Section (default options) -->
<TextBlock Style="{StaticResource CaptionTextBlockStyle}" Foreground="{ThemeResource TextFillColorSecondaryBrush}" Text="Index Capabilities of Index Instance (default options):" />
<StackPanel>
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowLightCardStyle}">
<TextBlock Grid.Column="0" Text="Lexical Text Capability Status:"/>
<TextBlock Grid.Column="1" x:Name="indexLexicalCapabilityResultText" Text="Unavailable"/>
</Grid>
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowCardStyle}">
<TextBlock Grid.Column="0" Text="Semantic Text Capability Status:"/>
<TextBlock Grid.Column="1" x:Name="indexSemanticCapabilityResultText" Text="Unavailable"/>
</Grid>
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowLightCardStyle}">
<TextBlock Grid.Column="0" Text="OCR Capability Status:"/>
<TextBlock Grid.Column="1" x:Name="indexOCRCapabilityResultText" Text="Unavailable"/>
</Grid>
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowCardStyle}">
<TextBlock Grid.Column="0" Text="Semantic Image Capability Status:"/>
<TextBlock Grid.Column="1" x:Name="indexSemanticImageCapabilityResultText" Text="Unavailable"/>
</Grid>
</StackPanel>

<TextBlock Style="{StaticResource CaptionTextBlockStyle}" Foreground="{ThemeResource TextFillColorSecondaryBrush}" Text="Index Capabilities of Index Instance:" />
<StackPanel>
<!-- Lexical Text Capability Status -->
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowLightCardStyle}">
<TextBlock Grid.Column="0" Text="Lexical Text Capability Status:"/>
<TextBlock Grid.Column="1" x:Name="indexLexicalCapabilityResultText" Text="Unavailable"/>
</Grid>
<!-- Semantic Text Capability Status -->
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowCardStyle}">
<TextBlock Grid.Column="0" Text="Semantic Text Capability Status:"/>
<TextBlock Grid.Column="1" x:Name="indexSemanticCapabilityResultText" Text="Unavailable"/>
</Grid>
<!-- OCR Capability Status -->
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowLightCardStyle}">
<TextBlock Grid.Column="0" Text="OCR Capability Status:"/>
<TextBlock Grid.Column="1" x:Name="indexOCRCapabilityResultText" Text="Unavailable"/>
</Grid>
<!-- Semantic Image Capability Status -->
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowCardStyle}">
<TextBlock Grid.Column="0" Text="Semantic Image Capability Status:"/>
<TextBlock Grid.Column="1" x:Name="indexSemanticImageCapabilityResultText" Text="Unavailable"/>
</Grid>
<!-- Suppressed Capabilities Demo Section -->
<TextBlock Style="{StaticResource CaptionTextBlockStyle}" Foreground="{ThemeResource TextFillColorSecondaryBrush}" Text="Suppressed Capabilities Demo (ImageOcr + ImageSemantic suppressed via GetOrCreateIndexWithOptions):" />
<StackPanel>
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowLightCardStyle}">
<TextBlock Grid.Column="0" Text="Lexical Text:"/>
<TextBlock Grid.Column="1" x:Name="suppressedTextLexicalText" Text="Loading..."/>
</Grid>
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowCardStyle}">
<TextBlock Grid.Column="0" Text="Semantic Text:"/>
<TextBlock Grid.Column="1" x:Name="suppressedTextSemanticText" Text="Loading..."/>
</Grid>
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowLightCardStyle}">
<TextBlock Grid.Column="0" Text="OCR (suppressed):"/>
<TextBlock Grid.Column="1" x:Name="suppressedOcrText" Text="Loading..."/>
</Grid>
<Grid Grid.ColumnDefinitions="*,*" Style="{StaticResource DesignRowCardStyle}">
<TextBlock Grid.Column="0" Text="Semantic Image (suppressed):"/>
<TextBlock Grid.Column="1" x:Name="suppressedImageSemanticText" Text="Loading..."/>
</Grid>
</StackPanel>

<InfoBar x:Name="IndexCapabilitiesMessage"
IsOpen="False"
Severity="Warning"
IsClosable="False"
Title="Some index capabilities are unavailable."
Padding="0">
<InfoBar.ActionButton>
<HyperlinkButton Content="Windows AI Troubleshooting"
NavigateUri="https://learn.microsoft.com/en-us/windows/ai/apis/troubleshooting" />
</InfoBar.ActionButton>
</InfoBar>
</StackPanel>

<InfoBar x:Name="IndexCapabilitiesMessage"
IsOpen="False"
Severity="Warning"
IsClosable="False"
Title="Some index capabilities are unavailable."
Padding="0">
<InfoBar.ActionButton>
<HyperlinkButton Content="Windows AI Troubleshooting"
NavigateUri="https://learn.microsoft.com/en-us/windows/ai/apis/troubleshooting" />
</InfoBar.ActionButton>
</InfoBar>
</StackPanel>
</Grid>
</Grid>
</ScrollViewer>
</samples:BaseSamplePage>
96 changes: 94 additions & 2 deletions AIDevGallery/Samples/WCRAPIs/AppIndexCapability.xaml.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,14 @@ protected override async Task LoadModelAsync(SampleNavigationParameters samplePa
{
await Task.Run(async () =>
{
// GetOrCreateIndex uses default options (all capabilities enabled).
// When using GetOrCreateIndexWithOptions, be aware of coupling rules:
// - Suppressing TextLexical is only honored when TextSemantic is also Suppressed;
// otherwise TextLexical suppression is silently treated as Default.
// - ImageOcr and ImageSemantic are independent; both must be Suppressed
// to fully disable image content.
// - Suppressing all text or all image capabilities makes that content kind
// unsupported (regions return UnsupportedContentKind).
var result = AppContentIndexer.GetOrCreateIndex("indexCapabilityIndex");

if (!result.Succeeded)
Expand Down Expand Up @@ -69,6 +77,9 @@ await Task.Run(async () =>

sampleParams.NotifyCompletion();
});

// Demonstrate GetOrCreateIndexWithOptions with suppressed capabilities
await DemoSuppressedCapabilitiesAsync();
}

protected override void OnNavigatedFrom(NavigationEventArgs e)
Expand Down Expand Up @@ -119,6 +130,10 @@ private async void LoadAppIndexCapabilities()

// Each status will be one of: Unknown, Initialized, Initializing, Suppressed, Unsupported, DisabledByPolicy, InitializationError
// If status is Initialized, that capability is ready for use
//
// Coupling rule: TextLexical suppression is only honored when
// TextSemantic is also Suppressed. If TextSemantic is Default or
// Required, TextLexical=Suppressed is silently treated as Default.
if (capabilities.GetCapabilityState(IndexCapability.TextLexical).InitializationStatus == IndexCapabilityInitializationStatus.Initialized)
{
indexLexicalCapabilityResultText.Text = "Available";
Expand All @@ -139,7 +154,10 @@ private async void LoadAppIndexCapabilities()
unavailable.Add("TextSemantic");
}

if (capabilities.GetCapabilityState(IndexCapability.ImageSemantic).InitializationStatus == IndexCapabilityInitializationStatus.Initialized)
// ImageOcr and ImageSemantic are independent capabilities; suppressing
// one does not affect the other. Both must be Suppressed to fully disable
// image content support.
if (capabilities.GetCapabilityState(IndexCapability.ImageOcr).InitializationStatus == IndexCapabilityInitializationStatus.Initialized)
{
indexOCRCapabilityResultText.Text = "Available";
}
Expand All @@ -149,7 +167,7 @@ private async void LoadAppIndexCapabilities()
unavailable.Add("ImageOcr");
}

if (capabilities.GetCapabilityState(IndexCapability.ImageOcr).InitializationStatus == IndexCapabilityInitializationStatus.Initialized)
if (capabilities.GetCapabilityState(IndexCapability.ImageSemantic).InitializationStatus == IndexCapabilityInitializationStatus.Initialized)
{
indexSemanticImageCapabilityResultText.Text = "Available";
}
Expand All @@ -172,6 +190,80 @@ private async void LoadAppIndexCapabilities()
});
}

/// <summary>
/// Demonstrates GetOrCreateIndexWithOptions to show how capability suppression
/// affects index behavior. Uses a dedicated temp index name to avoid
/// IncompatibleWithExistingOptions errors.
/// </summary>
private async Task DemoSuppressedCapabilitiesAsync()
{
await Task.Run(() =>
{
try
{
// First, delete any leftover temp index from a previous run
AppContentIndexer.DeleteIndex("capabilityDemoSuppressed", DeleteIndexWhileInUseBehavior.DeferIfInUse);

// Suppress both image capabilities to fully disable image content support.
// Per the IDL coupling rules:
// - ImageOcr and ImageSemantic are independent; both must be Suppressed
// to fully disable image content.
// - If only one is Suppressed, image content is still partially supported.
var options = new GetOrCreateIndexOptions
{
ImageOcrRequirement = IndexCapabilityRequirement.Suppressed,
ImageSemanticRequirement = IndexCapabilityRequirement.Suppressed,
};

var result = AppContentIndexer.GetOrCreateIndex("capabilityDemoSuppressed", options);

if (result.Succeeded)
{
using var tempIndexer = result.Indexer;
IndexCapabilities caps = tempIndexer.GetIndexCapabilities();

// Read values before leaving the using block to avoid use-after-dispose
var ocrState = caps.GetCapabilityState(IndexCapability.ImageOcr).InitializationStatus.ToString();
var imgSemanticState = caps.GetCapabilityState(IndexCapability.ImageSemantic).InitializationStatus.ToString();
var textLexState = caps.GetCapabilityState(IndexCapability.TextLexical).InitializationStatus.ToString();
var textSemState = caps.GetCapabilityState(IndexCapability.TextSemantic).InitializationStatus.ToString();

DispatcherQueue.TryEnqueue(() =>
{
suppressedOcrText.Text = ocrState;
suppressedImageSemanticText.Text = imgSemanticState;
suppressedTextLexicalText.Text = textLexState;
suppressedTextSemanticText.Text = textSemState;
});
}
else
{
DispatcherQueue.TryEnqueue(() =>
{
suppressedOcrText.Text = $"Error: {result.Status}";
suppressedImageSemanticText.Text = $"Error: {result.Status}";
suppressedTextLexicalText.Text = $"Error: {result.Status}";
suppressedTextSemanticText.Text = $"Error: {result.Status}";
});
}

// Clean up the temporary index
AppContentIndexer.DeleteIndex("capabilityDemoSuppressed", DeleteIndexWhileInUseBehavior.DeferIfInUse);
}
catch (Exception ex)
{
DispatcherQueue.TryEnqueue(() =>
{
suppressedOcrText.Text = "Error";
suppressedImageSemanticText.Text = "Error";
suppressedTextLexicalText.Text = "Error";
suppressedTextSemanticText.Text = "Error";
Debug.WriteLine($"DemoSuppressedCapabilitiesAsync failed: {ex.Message}");
});
}
});
}

private void Listener_IndexCapabilitiesChanged(AppContentIndexer indexer, IndexCapabilities statusResult)
{
LoadAppIndexCapabilities();
Expand Down
7 changes: 7 additions & 0 deletions AIDevGallery/Samples/WCRAPIs/KnowledgeRetrieval.xaml.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,13 @@ await Task.Run(async () =>
}

// Load AppContentIndexer
// GetOrCreateIndex uses default options (all capabilities enabled).
// To selectively suppress capabilities, use GetOrCreateIndexWithOptions.
// Coupling rules to keep in mind:
// - TextLexical suppression is only honored when TextSemantic is also
// Suppressed (semantic text requires the lexical pipeline).
// - ImageOcr and ImageSemantic are independent; both must be
// Suppressed to fully disable image content.
var result = AppContentIndexer.GetOrCreateIndex("knowledgeRetrievalIndex");

if (!result.Succeeded)
Expand Down
Loading