ai-dev-gallery adding-samples.instructions.md

Sample Implementation Instructions

When reviewing or creating sample code in AIDevGallery/Samples/:

Required Class Structure

Every sample MUST:

1. Inherit from BaseSamplePage
2. Have the [GallerySample] attribute with required properties
3. Override LoadModelAsync(SampleNavigationParameters) or LoadModelAsync(MultiModelSampleNavigationParameters)
4. Register cleanup in constructor via this.Unloaded += (s, e) => CleanUp();
5. Call sampleParams.NotifyCompletion() when model is ready

[GallerySample] Attribute

Required properties:

• Name: Display name
• Model1Types: Array of ModelType values
• Id: Unique GUID string
• Icon: Segoe MDL2 glyph code

Optional properties:

• Scenario: Reference a ScenarioType from scenarios.json
• Model2Types: For dual-model samples
• NugetPackageReferences: Required packages
• SharedCode: Array of SharedCodeEnum values
• AssetFilenames: Asset files needed by the sample

---

Language Model Samples (IChatClient)

For samples using language models (LLMs):

protected override async Task LoadModelAsync(SampleNavigationParameters sampleParams)
{
    try
    {
        chatClient = await sampleParams.GetIChatClientAsync();
    }
    catch (Exception ex)
    {
        ShowException(ex);
    }

    sampleParams.NotifyCompletion();
}

---

Windows ML

For samples using ONNX models with Windows ML / ONNX Runtime:

Initialization Flow

1. Ensure certified EPs - Install/register hardware acceleration packages (DML, QNN, etc.)
2. Create SessionOptions - Call RegisterOrtExtensions() for additional operators
3. Honor WinMlSampleOptions - Use Policy for auto-selection or EpName/DeviceType for specific EP
4. Create InferenceSession - Optionally use compiled model for faster subsequent runs
5. Call NotifyCompletion - Hide loading spinner when ready

LoadModelAsync Pattern

protected override async Task LoadModelAsync(SampleNavigationParameters sampleParams)
{
    try
    {
        await InitializeModelAsync(sampleParams.ModelPath, sampleParams.WinMlSampleOptions);
    }
    catch (Exception ex)
    {
        ShowException(ex, "Failed to load model.");
    }

    sampleParams.NotifyCompletion();
}