### Sample Directory Structure Example with Specifics

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/docs/samples-guidelines.md

Shows how to specify packaging and deployment details in the directory name, such as for unpackaged samples.

```text
\Samples
    \Activation
        \cs-wpf  (MSIX Packaged + Framework Packaged)
        \cs-wpf-unpackaged (Unpackaged + Framework Packaged)
        \cs-shared
        ...
        \cpp-console
```

--------------------------------

### Demonstrate Scenario-Based API Usage

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/docs/samples-guidelines.md

Show the correct sequence of API calls for a given scenario. This example demonstrates the proper order for starting, getting a value, and stopping a muffin object.

```csharp
void DemoGetValue_Click(object sender, RoutedEventArgs e)
{
    muffin.Start();
    int value = muffin.GetValue();
    rootPage.NotifyMessage($"Value is {value}", NotifyType.StatusMessage);
    muffin.Stop();
}
```

--------------------------------

### Sample Directory Structure Example

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/docs/samples-guidelines.md

Illustrates the recommended directory structure for organizing samples by feature, language, and UI framework.

```text
\Samples
     \<FeatureName>
          \<Language>-<UI Framework>
```

--------------------------------

### Run WindowsML Python Example

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/python/SqueezeNetPython/readme.md

Execute the main Python script to run the WindowsML machine learning example.

```python
python main.py
```

--------------------------------

### Install CMake and Ninja with winget

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cpp-cmake/WinMLEpCatalog/README.md

Installs CMake and Ninja using the winget package manager. Ensure these tools are available in your PATH.

```powershell
winget install --exact --id Kitware.CMake
winget install --exact --id Ninja-build.Ninja
```

--------------------------------

### Install Python Requirements (PowerShell)

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/python/SqueezeNetPython/readme.md

Run this PowerShell script to install the required WinML Python packages for the sample.

```powershell
./Install-Requirements.ps1
```

--------------------------------

### NuGet Package Version and Path Setup

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cpp-cmake/WinMLEpCatalog/CMakeLists.txt

Sets the NuGet package ID and version for Microsoft.Windows.AI.MachineLearning and determines the directory for package restoration.

```cmake
# NuGet package version
set(WINML_NUGET_ID      "Microsoft.Windows.AI.MachineLearning" CACHE STRING "NuGet package ID")
set(WINML_NUGET_VERSION "2.1.1"                      CACHE STRING "NuGet package version")

# Packages are restored / extracted under the build directory.
cmake_path(APPEND CMAKE_CURRENT_BINARY_DIR "packages" OUTPUT_VARIABLE WINML_PACKAGES_DIR)
```

--------------------------------

### Flat Folder Structure Example

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/AppLifecycle/Activation/README.md

Illustrates a flat folder structure for sample apps, where subfolders are directly under Activation. This structure is not adopted due to issues with Azure DevOps pipeline artifact naming conventions.

```plaintext
AppLifecycle\Activation\cpp-console-unpackaged
AppLifecycle\Activation\cpp-win32-packaged
...
AppLifecycle\Activation\cs-wpf-packaged
```

--------------------------------

### Initialize and Run Image Classification in WPF

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cs-wpf/README.md

Initializes execution providers, loads and preprocesses an image, runs inference using the SqueezeNet model, and processes the results to get top predictions. Ensure the WindowsML.Shared library is included for these helper methods.

```csharp
// Initialize execution providers
var catalog = ExecutionProviderCatalog.GetDefault();
await ModelManager.InitializeExecutionProvidersAsync(allowDownload: allowDownload);

// Load and preprocess image
var videoFrame = await ImageProcessor.LoadImageFileAsync(_selectedImagePath);
var inputTensor = await ImageProcessor.PreprocessImageAsync(videoFrame);

// Run inference
using var results = InferenceEngine.RunInference(_session, inputTensor);
var resultTensor = InferenceEngine.ExtractResults(_session, results);

// Process results
var topPredictions = ResultProcessor.GetTopPredictions(resultTensor, _labels, 5);

```

--------------------------------

### Image Classification Output Example

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cs-winforms/README.md

Displays the expected output format for top 5 image classification predictions with confidence percentages.

```text
Top 5 Predictions:
-------------------------------------------
Label                            Confidence
-------------------------------------------
French bulldog                       45.07%
bull mastiff                         35.05%
boxer                                 2.85%
pug                                   1.01%
American Staffordshire terrier        0.57%
-------------------------------------------

```

--------------------------------

### Initialize and Run Image Classification

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cs-winforms/README.md

Initializes execution providers, loads and preprocesses an image, runs inference, and processes the results to get top predictions. Ensure the WindowsML.Shared library is available.

```csharp
// Initialize execution providers
var catalog = ExecutionProviderCatalog.GetDefault();
await ModelManager.InitializeExecutionProvidersAsync(allowDownload: allowDownload);

// Load and preprocess image
using var videoFrame = await ImageProcessor.LoadImageFileAsync(_selectedImagePath);
var inputTensor = await ImageProcessor.PreprocessImageAsync(videoFrame);

// Run inference
using var results = InferenceEngine.RunInference(_session, inputTensor);
var resultTensor = InferenceEngine.ExtractResults(_session, results);

// Process results
var topPredictions = ResultProcessor.GetTopPredictions(resultTensor, _labels, 5);

```

--------------------------------

### Nested Folder Structure Example

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/AppLifecycle/Activation/README.md

Presents a nested folder structure for sample apps, which is more granular and could potentially work with Azure DevOps pipelines but was not adopted due to pipeline job limitations and performance concerns.

```plaintext
AppLifecycle\Activation\cpp\console\unpackaged
AppLifecycle\Activation\cpp\win32\packaged
AppLifecycle\Activation\cpp\win32\unpackaged
AppLifecycle\Activation\cpp\winui\packaged
AppLifecycle\Activation\cs\console\unpackaged
AppLifecycle\Activation\cs\winforms\unpackaged
AppLifecycle\Activation\cs\winui\packaged
AppLifecycle\Activation\cs\wpf\unpackaged
AppLifecycle\Activation\cs\wpf\packaged
```

--------------------------------

### Create ExpressionAnimation with string

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/SceneGraph/ExpressionBuilder/README.md

This example shows a traditional string-based ExpressionAnimation. ExpressionBuilder aims to replace this cumbersome method.

```csharp
_parallaxExpression = compositor.CreateExpressionAnimation(
	"(ScrollManipulation.Translation.Y + StartOffset - (0.5 * ItemHeight)) * ParallaxValue - 	(ScrollManipulation.Translation.Y + StartOffset - (0.5 * ItemHeight))"
);
```

--------------------------------

### Add WinAppSDK ContentIsland to Win32 App

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/Islands/README.md

This sample shows how to add a WinAppSDK ContentIsland with Xaml content to a Win32 app. It requires the Windows App SDK runtime to be installed.

```cpp
#include "pch.h"
#include "App.xaml.h"
#include "MainWindow.xaml.h"

using namespace winrt;
using namespace Windows::Foundation;

int __stdcall wWinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, PWSTR pCmdLine, int nCmdShow)
{
    // Initialize the Windows App SDK runtime.
    // This must be called before any other Windows App SDK APIs.
    // For unpackaged apps, this is done by calling Windows::WindowsAppRuntime::Initialize().
    // For packaged apps, this is done by calling Microsoft::Windows::ApplicationModel::AppList::AppListEntry::CreateAsync().
    // For this sample, we are an unpackaged app, so we call Initialize().
    auto initResult = Microsoft::Windows::ApplicationModel::AppList::AppListEntry::CreateAsync();
    if (initResult.Get().Status != Microsoft::Windows::ApplicationModel::AppList::AppListEntryStatus::Success)
    {
        // Handle error
        return -1;
    }

    // Initialize the WinRT.
    winrt::init_apartment(winrt::apartment_type::multi_threaded_apartment);

    // Create the application object.
    // The App object is needed for many of the Xaml controls to work, and it also enables metadata lookups for your app.
    App app;

    // Create the main window.
    MainWindow window;
    window.Activate();

    // Message loop.
    MSG msg = {};
    while (GetMessage(&msg, NULL, 0, 0))
    {
        TranslateMessage(&msg);
        DispatchMessage(&msg);
    }

    // Uninitialize the WinRT.
    winrt::uninit_apartment();

    return 0;
}

```

--------------------------------

### Build the Windows ML EP Catalog Sample

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cpp-cmake/WinMLEpCatalog/README.md

Builds the sample using a helper script with various configuration options. Supports different build types, generators, and platforms.

```powershell
# RelWithDebInfo for host architecture
.uild.ps1

# Debug with Visual Studio generator
.uild.ps1 -Generator VisualStudio -Configuration Debug

# Release for ARM64
.uild.ps1 -Configuration Release -Platform arm64

# Clean and rebuild
.uild.ps1 -Clean
```

--------------------------------

### Command-line Usage for ONNX Runtime Sample

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cpp/CppConsoleDesktop/README.md

This displays the available command-line options for the C++ Console Desktop sample. It details parameters for execution provider selection, model compilation, and input/output paths.

```text
CppConsoleDesktop.exe [options]
Options:
  --ep_policy <policy>           (Required*) Set execution provider selection policy (NPU, CPU, GPU, DEFAULT)
  --ep_name <name>               (Required*) Explicit execution provider name (mutually exclusive with --ep_policy)
  --compile                      Compile the model
  --download                     Download required packages
  --model <path>                 Path to input ONNX model (default: SqueezeNet.onnx in executable directory)
  --compiled_output <path>       Path for compiled output model (default: auto-generated with device info)
  --image_path <path>            Path to the input image (default: sample kitten image)

Exactly one of --ep_policy or --ep_name must be specified.
--use_model_catalog and --model are mutually exclusive.
```

--------------------------------

### Import Windows App SDK Package Props and Targets

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cpp/CppConsoleDesktop.FrameworkDependent/README.md

Import the `.props` and `.targets` files for the Foundation and InteractiveExperiences packages in the correct order within your `.vcxproj` file. This ensures proper integration of the Windows App SDK bootstrap mechanism.

```xml
<!-- In props section -->
<Import Project="packages\Microsoft.WindowsAppSDK.Foundation.[version]\build\native\Microsoft.WindowsAppSDK.Foundation.props" />
<Import Project="packages\Microsoft.WindowsAppSDK.InteractiveExperiences.[version]\build\native\Microsoft.WindowsAppSDK.InteractiveExperiences.props" />

<!-- In targets section -->
<Import Project="packages\Microsoft.WindowsAppSDK.Foundation.[version]\build\native\Microsoft.WindowsAppSDK.Foundation.targets" />
<Import Project="packages\Microsoft.WindowsAppSDK.InteractiveExperiences.[version]\build\native\Microsoft.WindowsAppSDK.InteractiveExperiences.targets" />
```

--------------------------------

### Command-line Usage for ONNX Runtime Sample

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cs/CSharpConsoleDesktop/README.md

This shows the available command-line options for the C# Console Desktop sample, including how to specify execution providers, compile models, and manage model paths.

```shell
CSharpConsoleDesktop.exe [options]
Options:
  --ep_policy <policy>           (Required*) Set execution provider selection policy (NPU, CPU, GPU, DEFAULT)
  --ep_name <name>               (Required*) Explicit execution provider name (mutually exclusive with --ep_policy)
  --compile                      Compile the model
  --download                     Download required packages
  --model <path>                 Path to input ONNX model (default: SqueezeNet.onnx in executable directory)
  --compiled_output <path>       Path for compiled output model (default: auto-generated with device info)
  --image_path <path>            Path to the input image (default: sample kitten image)

Exactly one of --ep_policy or --ep_name must be specified.
--use_model_catalog and --model are mutually exclusive.
```

--------------------------------

### Build and Run Project via Command Line

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cpp-abi/README.md

Use msbuild to build the CppAbiEPEnumerationSample.vcxproj project and then execute the generated application.

```powershell
# Build project
msbuild CppAbiEPEnumerationSample.vcxproj /p:Configuration=Release /p:Platform=x64

# Run executable
.\x64\Release\CppAbiEPEnumerationSample.exe
```

--------------------------------

### Manual Build and Run

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cpp-cmake/WinMLEpCatalog/README.md

Manually configures, builds, and runs the sample using CMake commands. This process includes restoring the NuGet package.

```powershell
# Configure (auto-restores the NuGet package)
cmake --preset nuget

# Build
cmake --build out/build/nuget --config RelWithDebInfo

# Run
.\out\build\nuget\WinMLEpCatalogSample.exe
```

--------------------------------

### Get Foundry Cache Location

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cs/HelloPhi/README.md

This command displays the directory where foundry stores downloaded models. You will need this path to locate your model files.

```cmd
foundry cache location
```

--------------------------------

### Initialize Image Description Generator

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsAIFoundry/cs-winui/Examples/ImageDescriptionInit.md

Ensures the Image Description Generator is ready for use. If not ready, it initiates the asynchronous deployment and waits for completion before creating a new session.

```csharp
if (ImageDescriptionGenerator.GetReadyState() == AIFeatureReadyState.NotReady)
{
    var imageDescriptionDeploymentOperation = ImageDescriptionGenerator.EnsureReadyAsync();
    await imageDescriptionDeploymentOperation;
}
ImageDescriptionGenerator _session = await ImageDescriptionGenerator.CreateAsync();
```

--------------------------------

### Initialize and Use Windows ML Components in C#

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cs-winui/README.md

This snippet demonstrates the core Windows ML workflow: initializing execution providers, loading and preprocessing an image, running inference, and processing the results. It relies on the `WindowsML.Shared` library for helper functions.

```csharp
// Initialize execution providers
var catalog = ExecutionProviderCatalog.GetDefault();
await ModelManager.InitializeExecutionProvidersAsync(allowDownload: allowDownload);

// Load and preprocess image
using var videoFrame = await ImageProcessor.LoadImageFileAsync(imagePath);
var inputTensor = await ImageProcessor.PreprocessImageAsync(videoFrame);

// Run inference
using var results = InferenceEngine.RunInference(_session, inputTensor);
var output = InferenceEngine.ExtractResults(_session, results);

// Process results
var topResults = ResultProcessor.GetTopPredictions(output, _labels, 5);
```

--------------------------------

### Replace Azure AppId

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/Notifications/Push/README.md

Replace the placeholder GUID with your Azure AppId to correctly obtain the WNS Channel URI. This is required for the sample to function.

```cpp
winrt::guid remoteId{ "00000000-0000-0000-0000-000000000000"}; 
```

--------------------------------

### Generate Language Model Response

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsAIFoundry/cs-winui/Examples/LanguageModel.md

Use the GenerateResponseAsync method to get a response from the language model. Ensure the model is properly initialized before calling this method.

```csharp
var languageModelResponse = await model.GenerateResponseAsync(prompt);
string response = languageModelResponse.Response;
```

--------------------------------

### Automatic Package Restore and Extraction

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cpp-cmake/WinMLEpCatalog/CMakeLists.txt

Handles the automatic restoration and extraction of the WinML NuGet package if the package directory is not explicitly defined. It supports local .nupkg files and nuget install commands.

```cmake
#  Auto-restore & extract
# Users can still skip all of this by setting microsoft.windows.ai.machinelearning_DIR.
if(NOT DEFINED microsoft.windows.ai.machinelearning_DIR)
    set(_winml_pkg_name  "${WINML_NUGET_ID}.${WINML_NUGET_VERSION}")
    cmake_path(APPEND WINML_PACKAGES_DIR "${_winml_pkg_name}" OUTPUT_VARIABLE _winml_extract_dir)
    cmake_path(APPEND _winml_extract_dir "build/cmake/microsoft.windows.ai.machinelearning-config.cmake"
        OUTPUT_VARIABLE _winml_config_file)

    if(NOT EXISTS "${_winml_config_file}")
        # Try a local .nupkg first (handy for pre-release testing).
        cmake_path(APPEND CMAKE_CURRENT_SOURCE_DIR "${_winml_pkg_name}.nupkg"
            OUTPUT_VARIABLE _winml_local_nupkg)
        if(EXISTS "${_winml_local_nupkg}")
            file(MAKE_DIRECTORY "${_winml_extract_dir}")
            message(STATUS "Extracting local ${_winml_local_nupkg}")
            file(ARCHIVE_EXTRACT INPUT "${_winml_local_nupkg}" DESTINATION "${_winml_extract_dir}")
        else()
            # Restore via nuget install using the repo's NuGet.Config.
            find_program(_NUGET_EXE nuget REQUIRED)
            cmake_path(ABSOLUTE_PATH WINML_NUGET_CONFIG NORMALIZE OUTPUT_VARIABLE _winml_nuget_cfg)
            message(STATUS "Restoring ${_winml_pkg_name} via nuget install (config: ${_winml_nuget_cfg})")
            execute_process(
                COMMAND "${_NUGET_EXE}" install "${WINML_NUGET_ID}"
                        -Version "${WINML_NUGET_VERSION}"
                        -OutputDirectory "${WINML_PACKAGES_DIR}"
                        -ConfigFile "${_winml_nuget_cfg}"
                        -NonInteractive -DirectDownload
                        -DependencyVersion Ignore
                RESULT_VARIABLE _nuget_result
            )
            if(NOT _nuget_result EQUAL 0)
                message(FATAL_ERROR
                    "nuget install failed (exit ${_nuget_result}). "
                    "Place ${_winml_pkg_name}.nupkg in this directory or check your NuGet sources.")
            endif()
        endif()
    endif()

    if(NOT EXISTS "${_winml_config_file}")
        message(FATAL_ERROR "CMake config not found after restore: ${_winml_config_file}")
    endif()

    cmake_path(APPEND _winml_extract_dir "build/cmake" OUTPUT_VARIABLE _winml_cmake_dir)
    set(microsoft.windows.ai.machinelearning_DIR "${_winml_cmake_dir}"
        CACHE PATH "Path to microsoft.windows.ai.machinelearning CMake config" FORCE)
endif()
```

--------------------------------

### Project Configuration

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cpp-cmake/WinMLEpCatalog/CMakeLists.txt

Defines the minimum required CMake version and sets up the project with its version, description, and primary language.

```cmake
cmake_minimum_required(VERSION 3.21)

project(WinMLEpCatalogSample
    VERSION 1.0.0
    DESCRIPTION "Windows ML Execution Provider Catalog Sample with ONNX Runtime Integration"
    LANGUAGES CXX
)
```

--------------------------------

### Control UI Element States for Scenario Flow

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/docs/samples-guidelines.md

Use UI element enabled/disabled states to guide users through the correct order of operations for an API. This prevents incorrect usage and simplifies error handling.

```csharp
void ResetScenario()
{
    StartButton.IsEnabled = true;
    GetValueButton.IsEnabled = false;
    StopButton.IsEnabled = false;
}

void Start_Click(object sender, RoutedEventArgs e)
{
    muffin.Start();
    StartButton.IsEnabled = false; // cannot start twice
    GetValueButton.IsEnabled = true; // must start before getting the value
    StopButton.IsEnabled = true; // cannot stop unless started
}

void GetValue_Click(object sender, RoutedEventArgs e)
{
    int value = muffin.GetValue();
    rootPage.NotifyMessage($"Value is {value}", NotifyType.StatusMessage);
}

void Stop_Click(object sender, RoutedEventArgs e)
{
    muffin.Stop();
    GetValueButton.IsEnabled = false; // must start again before getting the value
    StopButton.IsEnabled = false; // cannot stop twice
    StartButton.IsEnabled = true; // you can start it again
}
```

--------------------------------

### Create DispatcherQueueController

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/Islands/README.md

Demonstrates creating a DispatcherQueueController on the UI thread and a System DispatcherQueueController on a dedicated rendering thread.

```cpp
// Create a DispatcherQueueController on the UI thread.
auto controller = winrt::Windows::System::DispatcherQueueController::CreateDefaultController();
auto dispatcherQueue = controller.DispatcherQueue();

// Create a System DispatcherQueueController on a dedicated rendering thread.
auto systemController = winrt::Windows::System::DispatcherQueueController::CreateOnDedicatedThread();
auto systemDispatcherQueue = systemController.DispatcherQueue();

```

--------------------------------

### Create Executable

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cpp-cmake/WinMLEpCatalog/CMakeLists.txt

Defines the main executable target for the sample application.

```cmake
add_executable(WinMLEpCatalogSample
    main.cpp
)
```

--------------------------------

### Configure WindowsAppSdkBootstrapInitialize Property

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cpp/CppConsoleDesktop.FrameworkDependent/README.md

Set the `WindowsAppSdkBootstrapInitialize` property to `true` in your `.vcxproj` file before importing any Windows App SDK packages. This enables the automatic bootstrap initialization for framework-dependent applications.

```xml
<PropertyGroup>
  <WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize>
</PropertyGroup>
```

--------------------------------

### List Available Models with Foundry

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cs/HelloPhi/README.md

Use this command to list available models, filtering by alias. This helps identify models suitable for your needs.

```cmd
c:\> foundry model ls --filter alias=phi-3-mini-128k
```

--------------------------------

### Download Model with Foundry

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cs/HelloPhi/README.md

Download a specific model using the 'foundry model download' command. Ensure you have the correct model alias.

```cmd
foundry model download Phi-3-mini-128k-instruct-generic-cpu
```

--------------------------------

### Sample Metadata YAML Front-Matter

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/docs/samples-guidelines.md

Include this YAML front-matter in your sample's README.md file to integrate with the Docs Samples Browser. Ensure all fields are accurately populated.

```yaml
---
page_type: sample
languages:
- csharp
- cppwinrt
- cpp
products:
- windows
- windows-app-sdk
name: "Photo Editor"
urlFragment: PhotoEditor
description: "Shows how to retrieve photos from the Pictures library, and then edit the selected image with assorted photo effects."
extendedZipContent:
- path: LICENSE
  target: LICENSE
---
```

--------------------------------

### Download Test Model (PowerShell)

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/python/SqueezeNetPython/readme.md

Execute this PowerShell script to download the necessary test model for the WindowsML sample.

```powershell
../Download-Model.ps1
```

--------------------------------

### Discover and Display Execution Provider Information

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cpp/CppConsoleDesktop/README.md

This C++ code snippet demonstrates how to discover available execution providers and display their information, including provider name, vendor, and device type. It organizes devices by EP name for clarity.

```cpp
#include <win_onnxruntime_cxx_api.h>

  // Accumulate devices by ep_name
  // Passing all devices for a given EP in a single call allows the execution provider
  // to select the best configuration or combination of devices, rather than being limited
  // to a single device. This enables optimal use of available hardware if supported by the EP.
  std::unordered_map<std::string, std::vector<Ort::ConstEpDevice>> ep_device_map;
  for (const auto& device : ep_devices)
  {
      ep_device_map[device.EpName()].push_back(device);
  }
  std::wcout << L"Execution Provider Information:\n";
  std::wcout << L"-------------------------------------------------------------\
";
  std::wcout << L"Provider" << std::left << std::setw(32) << L"" << std::setw(16) << L"Vendor" << std::setw(12)
              << L"Device Type" << std::endl;
  std::wcout << L"-------------------------------------------------------------\
";
  for (const auto& [ep_name, devices] : ep_device_map)
  {
      std::cout << std::left << std::setw(32) << ep_name;
      for (const auto& device : devices)
      {
          std::cout << std::setw(16) << device.EpVendor() << std::setw(12) << ToString(device.Device().Type())
                      << std::endl;
      }
  }

// Configure and add each EP with appropriate options
for (const auto& [ep_name, devices] : ep_device_map)
{
    Ort::KeyValuePairs ep_options;
    if (ep_name == "VitisAIExecutionProvider")
    {
        // Append the Vitis AI EP
        session_options.AppendExecutionProvider_V2(env, devices, ep_options);
        std::cout << "Successfully added " << ep_name << " EP" << std::endl;
    }
    // ... other providers
}
```

--------------------------------

### Avoid Scratchpad Code in Samples

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/docs/samples-guidelines.md

Do not use scratchpad code that demonstrates API usage without context or proper error handling. Focus on showing correct order of operations and relevant error checks.

```csharp
void Start_Clicked(object sender, RoutedEventArgs e)
{
    try
    {
        muffin.Start();
    }
    catch (Exception ex)
    {
        rootPage.NotifyMessage($
```

--------------------------------

### Configure LanguageModelWithOptionsAndProgress

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsAIFoundry/cs-winui/Examples/LanguageModelWithOptionsAndProgress.md

Configure LanguageModelWithOptionsAndProgress with custom options for content filtering and progress reporting. This is useful when you need to control the severity levels of blocked content in prompts and responses.

```csharp
var languageModelOptions = new LanguageModelOptions(); // default options

var promptMinSeverityLevelToBlock = new TextContentFilterSeverity {
    HateContentSeverity = SeverityLevel.Low,
    SexualContentSeverity = SeverityLevel.Low,
    ViolentContentSeverity = SeverityLevel.Medium,
    SelfHarmContentSeverity = SeverityLevel.Low
};

var responseMinSeverityLevelToBlock = new TextContentFilterSeverity {
    HateContentSeverity = SeverityLevel.Low,
    SexualContentSeverity = SeverityLevel.Low,
    ViolentContentSeverity = SeverityLevel.Low,
    SelfHarmContentSeverity = SeverityLevel.Medium
};

var contentFilterOptions = new ContentFilterOptions {
    PromptMinSeverityLevelToBlock = promptMinSeverityLevelToBlock,
    ResponseMinSeverityLevelToBlock = responseMinSeverityLevelToBlock
};

IProgress<string> progress;
var languageModelResponseWithProgress = model.GenerateResponseWithProgressAsync(languageModelOptions, prompt, contentFilterOptions);
languageModelRepsonseWithProgress.Progress = (_, generationProgress) =>
{
    progress.Report(generationProgress);
};
string response = (await languageModelResponseWithProgress).Response;
```

--------------------------------

### Initialize and Create Inference Session

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cs/CSharpConsoleDesktop/README.md

Initializes execution providers and creates an inference session using shared helper methods. Ensure ModelManager.InitializeExecutionProvidersAsync is called before creating the session.

```csharp
using Microsoft.ML.OnnxRuntime;
using WindowsML.Shared;

// Initialize execution providers using shared helper  
await ModelManager.InitializeExecutionProvidersAsync(options.Download);

// Create inference session with EP configuration using shared helper
using InferenceSession session = ModelManager.CreateSession(actualModelPath, options, ortEnv);
```

--------------------------------

### Ensure TextRecognizer is Ready and Create Instance

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsAIFoundry/cs-winui/Examples/TextRecognizerInit.md

Before creating a TextRecognizer instance, check its ready state and ensure it's ready for use. This involves an asynchronous operation that might download necessary models.

```csharp
if (TextRecognizer.GetReadyState() == AIFeatureReadyState.NotReady)
{
    var textRecognizerDeploymentOperation = TextRecognizer.EnsureReadyAsync();
    await textRecognizerDeploymentOperation;
}
TextRecognizer _session = await TextRecognizer.CreateAsync();
```

--------------------------------

### Connect ContentIsland with System ContentIsland

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/Islands/README.md

Connects a ContentIsland with a System ContentIsland. This is useful for embedding content from one framework into another.

```cpp
// Create the parent System ContentIsland.
auto parentIsland = winrt::Microsoft::Windows::Widgets::Composition::ContentIsland::CreateInstance();

// Create the child ContentIsland.
auto childIsland = winrt::Microsoft::Windows::Widgets::Composition::ContentIsland::CreateInstance();

// Connect the child to the parent.
parentIsland.ConnectChild(childIsland);

```

--------------------------------

### Run App in Packaged Self-Contained Mode (ARM64)

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsAIFoundry/cs-winui/README.md

Use this command to run the application as an ARM64 application in packaged self-contained mode. This is required for apps using Windows AI APIs.

```powershell
dotnet run -p:Configuration=Debug -p:Platform=ARM64 -p:WindowsAppSDKSelfContained=true -p:SelfContained=true.
```

--------------------------------

### Connect System ContentIsland with System ContentIsland

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/Islands/README.md

Connects a System ContentIsland with another System ContentIsland. This allows for nesting of UI elements across different frameworks.

```cpp
// Create the parent System ContentIsland.
auto parentIsland = winrt::Microsoft::Windows::Widgets::Composition::ContentIsland::CreateInstance();

// Create the child System ContentIsland.
auto childIsland = winrt::Microsoft::Windows::Widgets::Composition::ContentIsland::CreateInstance();

// Connect the child to the parent.
parentIsland.ConnectChild(childIsland);

```

--------------------------------

### Convert Text to Table

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsAIFoundry/cs-winui/Examples/TextIntelligenceTextToTable.md

Initializes the LanguageModel and TextToTableConverter, then converts a prompt into a table. Iterates through the resulting rows and prints their columns.

```csharp
using LanguageModel languageModel = await LanguageModel.CreateAsync();
var textToTableConverter = new TextToTableConverter(languageModel);

var response = await textToTableConverter.ConvertAsync(prompt);

if (rows != null)
{
    foreach (var row in rows)
    {
        Console.WriteLine(string.Join(',', row.GetColumns()));
    }
}
```

--------------------------------

### Generate Image Description

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsAIFoundry/cs-winui/Examples/ImageDescription.md

Use this snippet to generate a brief description of an image. Ensure you have a valid SoftwareBitmap and an initialized Session. ContentFilterOptions can be customized based on your needs.

```csharp
SoftwareBitmap inputImage;
ImageBuffer imageBuffer = ImageBuffer.CreateCopyFromBitmap(inputImage);

// Image Description Scenario and Content Filter Options can be chosen as per scenario
ContentFilterOptions filterOptions = new();
var modelResponse = await Session.DescribeAsync(inputImage, ImageDescriptionKind.BriefDescription, filterOptions);
if (modelResponse.Status != ImageDescriptionResultStatus.Complete)
{
    return $"Image description failed with status: {modelResponse.Status}";
}
return modelResponse.Description;
```

--------------------------------

### Run GenAI Model from Command Line

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cpp/CppConsoleDesktop.GenAI/README.md

This command executes the GenAI model using the .NET CLI. Provide the model path using the '-m' argument.

```cmd
dotnet run -- -m %USERPROFILE%\.foundry\cache\models\Microsoft\Phi-3.5-mini-instruct-generic-cpu\cpu-int4-rtn-block-32-acc-level-4
```

--------------------------------

### Add NuGet Packages for Framework-Dependent Deployment

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cpp/CppConsoleDesktop.FrameworkDependent/README.md

Include these packages in your `packages.config` file for framework-dependent deployment. Ensure you use the appropriate version placeholders.

```xml
<package id="Microsoft.WindowsAppSDK.Foundation" version="[version]" targetFramework="native" />
<package id="Microsoft.WindowsAppSDK.InteractiveExperiences" version="[version]" targetFramework="native" />
<package id="Microsoft.WindowsAppSDK.Runtime" version="[version]" targetFramework="native" />
<package id="Microsoft.WindowsAppSDK.Base" version="[version]" targetFramework="native" />
```

--------------------------------

### Summarize Text with Progress Reporting

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsAIFoundry/cs-winui/Examples/TextIntelligenceSummarize.md

Use this snippet to summarize text and receive progress updates. Ensure you have initialized the LanguageModel and TextSummarizer, and have an IProgress<string> implementation for reporting.

```csharp
IProgress<string> progress;
using LanguageModel languageModel = await LanguageModel.CreateAsync();
var textSummarizer = new TextSummarizer(languageModel);

var textSummarizerResponseWithProgress = textSummarizer.SummarizeAsync(prompt);

string progressText = string.Empty;
textSummarizerResponseWithProgress.Progress = (_, generationProgress) =>
{
    progress.Report(generationProgress);
};
var response = await textSummarizerResponseWithProgress;
```

--------------------------------

### Generate Response with Progress

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsAIFoundry/cs-winui/Examples/LanguageModelWithTexIntelligenceSkills.md

Configures LanguageModelOptions for rewriting text and generates a response asynchronously with progress updates. Ensure you have an IProgress<string> implementation to receive progress notifications.

```csharp
var languageModelOptions = new LanguageModelOptions {
    Skill = LanguageModelSkill.Rewrite,
    Temp =  0.9f,
    Top_p = 0.9f,
    Top_k = 40
};

IProgress<string> progress;
//uses default value for content filtering
var languageModelResponseWithProgress = model.GenerateResponseWithProgressAsync(languageModelOptions, prompt);
languageModelRepsonseWithProgress.Progress = (_, generationProgress) =>
{
    progress.Report(generationProgress);
};
string response = (await languageModelResponseWithProgress).Response;
```

--------------------------------

### C#/C++ Copyright Header

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/docs/samples-guidelines.md

Include this copyright and license notice at the header of C# and C++ files.

```csharp
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.
```

--------------------------------

### Create New Feature CI Pipeline YAML

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/docs/samples-guidelines.md

Create a new YAML file at the root of the repository for a feature's CI pipeline. This file defines the pipeline stages and points to the shared WindowsAppSDK-SamplesCI.yml template.

```yaml
name: $(BuildDefinitionName)_$(date:yyMM).$(date:dd)$(rev:rrr)
stages:
- template: WindowsAppSDK-SamplesCI.yml
  parameters:
    FeatureDirectory: "<FeatureName>"
```

--------------------------------

### Ensure LanguageModel Readiness and Create Session

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsAIFoundry/cs-winui/Examples/LanguageModelInit.md

Check if the LanguageModel is ready. If not, asynchronously ensure it's ready before creating a session. This is crucial for operations that depend on the model being fully initialized.

```csharp
if (LanguageModel.GetReadyState() == AIFeatureReadyState.NotReady)
{
    var languageModelDeploymentOperation = LanguageModel.EnsureReadyAsync();
    await languageModelDeploymentOperation;
}
LanguageModel _session = await LanguageModel.CreateAsync();
```

--------------------------------

### Scale SoftwareBitmap

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsAIFoundry/cs-winui/Examples/ImageScaler.md

Scales a SoftwareBitmap to the specified dimensions using the ImageScaler model. Ensure the input image and dimensions are valid before calling.

```csharp
SoftwareBitmap inputImage;
int width, height;
SoftwareBitmap result = model.ScaleSoftwareBitmap(inputImage, width, height);
```

--------------------------------

### Ensure ImageScaler Ready and Create Session

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsAIFoundry/cs-winui/Examples/ImageScalerInit.md

Checks if ImageScaler is ready and ensures it is by calling EnsureReadyAsync if necessary. Then, it creates a new ImageScaler session.

```csharp
if (ImageScaler.GetReadyState() == AIFeatureReadyState.NotReady)
{
    var imageScalerDeploymentOperation = ImageScaler.EnsureReadyAsync();
    await imageScalerDeploymentOperation;
}
ImageScaler _session = await ImageScaler.CreateAsync();
```

--------------------------------

### Layout: Top-level window resize

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/Islands/README.md

Handles top-level window resize events to ensure the ContentIsland's layout adapts correctly. This is essential for responsive UIs.

```cpp
// Example of handling window resize (conceptual)
// This would typically involve listening to window size change notifications and updating the ContentIsland's size and layout accordingly.
// For example, in Win32, you would handle WM_SIZE messages.

```

--------------------------------

### Input Processing: Keyboard Accelerators

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/Islands/README.md

Implements keyboard accelerators (shortcuts) for actions within a ContentIsland. This enhances user efficiency by providing quick access to commands.

```cpp
// Example of registering a keyboard accelerator (conceptual)
// This would typically be done within the Xaml content or a framework-specific handler.
// For example, in WinUI, you might use Input.KeyTipService or similar mechanisms.

```

--------------------------------

### C# Automatically-typed Variable Constructor-like Pattern

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/docs/samples-guidelines.md

Use 'var' for well-known constructor-like patterns like 'GetForCurrentView' or 'GetDefault'.

```csharp
var override = BrightnessOverride.GetForCurrentView();
var barometer = Barometer.GetDefault();
```

--------------------------------

### Automatic ABI Header Generation Configuration

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cpp-abi/README.md

Configure the build process to generate ABI headers specifically for Windows ML APIs and specify the Windows SDK version for metadata resolution.

```xml
<PropertyGroup>
  <!-- Filter ABI generation to Windows ML APIs only -->
  <AbiWinRTFilter>Microsoft.Windows.AI.MachineLearning</AbiWinRTFilter>
  <!-- Windows SDK version for metadata resolution -->
  <WindowsSDKVersion>10.0.26100.0</WindowsSDKVersion>
</PropertyGroup>
```

--------------------------------

### Connect ContentIsland with DesktopPopupSiteBridge

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/Islands/README.md

Connects a ContentIsland with a DesktopPopupSiteBridge. This is used to host popup content within a ContentIsland.

```cpp
// Create a DesktopPopupSiteBridge.
auto popupSiteBridge = winrt::Microsoft::Windows::Widgets::Composition::DesktopPopupSiteBridge::CreateInstance(nullptr); // Pass a parent ContentIsland if available

// Create a ContentIsland to be hosted.
auto contentIsland = winrt::Microsoft::Windows::Widgets::Composition::ContentIsland::CreateInstance();

// Connect the ContentIsland with the DesktopPopupSiteBridge.
popupSiteBridge.Connect(contentIsland);

```

--------------------------------

### Compile ONNX Model with Options

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsML/cs/CSharpConsoleDesktop/README.md

Compiles an ONNX model using OrtModelCompilationOptions, setting input and output paths. The compilation process measures and reports the time taken. Handles potential compilation failures gracefully.

```csharp
// Create compilation options from session options
OrtModelCompilationOptions compileOptions = new(sessionOptions);

try
{
    // Set input and output model paths
    compileOptions.SetInputModelPath(modelPath);
    compileOptions.SetOutputModelPath(compiledModelPath);

    Console.WriteLine("Starting compile, this may take a few moments...");
    DateTime start = DateTime.Now;

    // Compile the model
    compileOptions.CompileModel();

    TimeSpan duration = DateTime.Now - start;
    Console.WriteLine($"Model compiled successfully in {duration.TotalMilliseconds} ms");
}
catch
{
    Console.Error.WriteLine($"Failed to compile model, continuing ...");
}
```

--------------------------------

### Initialize Image Object Remover

Source: https://github.com/microsoft/windowsappsdk-samples/blob/main/Samples/WindowsAIFoundry/cs-winui/Examples/ImageObjectRemoverInit.md

Checks if the Image Object Remover is ready and ensures it is ready by calling EnsureReadyAsync if necessary. Then, it creates an instance of the Image Object Remover.

```csharp
IProgress<PackageDeploymentProgress> progress;
if (ImageObjectRemover.GetReadyState() == AIFeatureReadyState.NotReady)
{
    var imageObjectRemoverDeploymentOperationAsync = ImageObjectRemover.EnsureReadyAsync();
    await imageObjectRemoverDeploymentOperationAsync;
}
ImageObjectRemover model = await ImageObjectRemover.CreateAsync();
```