クイック スタート: MXC SDK を使用してワークロードを実行する

.NET、TypeScript、または Rust SDK を使用して、Windows のプロセス分離モードでコマンドを実行します。 各例では、サンプル入力を作成してワークロードによる読み取りを許可し、別の出力フォルダーへの書き込みアクセスを許可します。 ネットワークと UI のアクセス許可は拒否されたままです。

ホスト アプリがポリシーを作成し、実行結果を処理します。 コマンドは MXC 内で実行されますが、ホスト アプリのその他の部分は MXC 内では実行されません。

この例では、MXC 1.0 V1 SDK API を使用しています。 V1 SDK では、安定した 1.0.0 スキーマが内部的に使用されるため、要求でスキーマ バージョンを指定しないでください。 互換性のあるスキーマの選択を参照してください。

Prerequisites

必要なもの:

• サポートされた ProcessContainer 環境を備えた Windows 11 バージョン 24H2 以降。
• C# の場合は、.NET 8 SDK 以降と Microsoft.Mxc.Sdk NuGet パッケージ。
• TypeScript の場合は、npm、@microsoft/mxc-sdk パッケージ、および Node.js 24 系列の 24.21.0 以降、または Node.js 26.8.0 以降。
• Rust の場合、MSVC ビルド ツール対応の安定した Rust ツールチェーンと、mxc-sdk クレートが必要です。 「Windowsで Rust 開発環境を設定する」を参照してください。
• セットアップ コマンド用の書き込み可能な作業ディレクトリと PowerShell。

この手順では、NuGet.org、npm、および crates.io の MXC 1.0 パッケージを使用します。 MXC ソース ビルドは必要ありません。

この例を実行する前に、対応プラットフォームを確認してください。 サポートされているWindows バージョンでは、すべてのオプション機能が利用できるわけではありません。

一部のホストでは、MXC は AppContainer ベースのフォールバック 層でプロセス分離を実行します。 そのレベルでは、システム ドライブと null デバイスの 1 回限りの準備が必要であり、null デバイスの設定は再起動するたびにリセットされます。 必要な事前準備が完了していない場合、MXC のホスト プローブは、実行すべき wxc-host-prep.exe のサブコマンドを示す警告を返します。 TypeScript の例では、getPlatformSupport() からこれらの警告が出力されます。また、wxc-exec.exe --probe を実行してホストを確認することもできます。 wxc-host-prep.exe の実行には管理者の承認が必要なため、アプリから実行するのではなく、管理者に推奨コマンドの実行を依頼してください。 詳細については、「 ホストの準備」を参照してください。

1. プロジェクトを作成する

.NET

コンソール アプリを作成し、NuGet.org から MXC パッケージを追加します。

dotnet new console -n MxcQuickstart
Set-Location MxcQuickstart
dotnet add package Microsoft.Mxc.Sdk

TypeScript

Node.js プロジェクトを作成して MXC をインストールし、TypeScript の例を実行するために tsx を追加します。

New-Item -ItemType Directory MxcQuickstart
Set-Location MxcQuickstart
npm init -y
npm pkg set type=module
npm install @microsoft/mxc-sdk
npm install --save-dev tsx

錆

バイナリ クレートを作成し、crates.io から MXC クレートを追加します。

cargo new mxc-quickstart
Set-Location mxc-quickstart
cargo add mxc-sdk

2. ワークロードを定義して実行する

プロセスの分離は、選択したホスト ファイルが必要であり、環境が保持されていないため、この短時間しか実行されないコマンドに適しています。 ワークロードによっては、別のコンテインメントの種類が必要になる場合があります。

ホストはプロジェクト ディレクトリの下に workspace\input と workspace\output を作成します。 含まれているコマンドは、 input.txt を読み取り、 result.txtを書き込みます。 入力ディレクトリへの書き込みアクセス権や、他のプロジェクト ファイルへのアクセス権はありません。

ホストは、独自の変数を継承するのではなく、小規模で明示的な環境を提供します。 Windows ProcessContainer ワークロード用の環境を提供する場合は、SystemRootとLOCALAPPDATAの両方を含めます。 どちらか一方が欠けている場合、MXC は起動前に要求を拒否します。 この例では、許可された出力ディレクトリに LOCALAPPDATA、 TEMP、および TMP をポイントして、一時ファイルとユーザーごとのファイルがポリシー内に留まるようにします。

.NET

Program.csを次のように置き換えます。

using Microsoft.Mxc.Sdk.V1;

if (!OperatingSystem.IsWindows())
{
    Console.Error.WriteLine("This example requires Windows.");
    return 1;
}

try
{
    var support = MxcPlatform.GetPlatformSupport();
    if (!support.IsSupported ||
        !support.AvailableMethods.Contains(ContainmentBackend.ProcessContainer))
    {
        Console.Error.WriteLine(support.Reason ?? "Windows ProcessContainer is unavailable.");
        return 1;
    }

    string inputDirectory = Path.GetFullPath(@"workspace\input");
    string outputDirectory = Path.GetFullPath(@"workspace\output");
    string outputFile = Path.Combine(outputDirectory, "result.txt");
    string commandInterpreter = Path.Combine(Environment.SystemDirectory, "cmd.exe");

    Directory.CreateDirectory(inputDirectory);
    Directory.CreateDirectory(outputDirectory);
    File.WriteAllText(Path.Combine(inputDirectory, "input.txt"), "Hello from MXC!\n");

    var request = new ContainerRequest(
        $"\"{commandInterpreter}\" /d /c type input.txt > \"{outputFile}\"")
    {
        Containment = new Containment.Process(),
        Filesystem = new FilesystemPolicy
        {
            ReadonlyPaths = { inputDirectory, commandInterpreter },
            ReadwritePaths = { outputDirectory },
        },
        // Omitted network and UI permissions remain denied.
        WorkingDirectory = inputDirectory,
        Environment = new()
        {
            ["SystemRoot"] = Environment.GetFolderPath(Environment.SpecialFolder.Windows),
            ["LOCALAPPDATA"] = outputDirectory,
            ["TEMP"] = outputDirectory,
            ["TMP"] = outputDirectory,
        },
        TimeoutMs = 30_000,
    };

    ExecutionResult result = await MxcContainer.RunAsync(request);
    Console.Write(result.Stdout);
    Console.Error.Write(result.Stderr);
    foreach (string warning in result.Warnings)
    {
        Console.Error.WriteLine(warning);
    }

    if (result.TimedOut)
    {
        Console.Error.WriteLine("The workload exceeded its timeout.");
        return 1;
    }

    Console.WriteLine($"Sandbox exited with code {result.ExitCode}");
    if (result.ExitCode == 0)
    {
        Console.Write(File.ReadAllText(outputFile));
    }
    return result.ExitCode;
}
catch (MxcException ex)
{
    Console.Error.WriteLine(ex);
    if (ex.Remediation is not null)
    {
        Console.Error.WriteLine(ex.Remediation);
    }
    return 1;
}

次のようにアプリを実行します。

dotnet run

TypeScript

以下で sandbox.ts を作成:

import {
  getPlatformSupport,
  MxcError,
  run,
  type ContainerRequest,
} from '@microsoft/mxc-sdk/v1';
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { join, resolve } from 'node:path';

try {
  const systemRoot = process.env.SystemRoot;
  if (process.platform !== 'win32' || !systemRoot) {
    throw new Error('This example requires Windows and SystemRoot.');
  }

  const support = getPlatformSupport();
  if (!support.isSupported || !support.availableMethods.includes('processcontainer')) {
    throw new Error(support.reason ?? 'Windows ProcessContainer is unavailable.');
  }
  for (const warning of support.isolationWarnings ?? []) {
    console.error(warning);
  }

  const inputDirectory = resolve('workspace', 'input');
  const outputDirectory = resolve('workspace', 'output');
  const outputFile = join(outputDirectory, 'result.txt');
  const commandInterpreter = join(systemRoot, 'System32', 'cmd.exe');

  mkdirSync(inputDirectory, { recursive: true });
  mkdirSync(outputDirectory, { recursive: true });
  writeFileSync(join(inputDirectory, 'input.txt'), 'Hello from MXC!\n');

  const request: ContainerRequest = {
    command: `"${commandInterpreter}" /d /c type input.txt > "${outputFile}"`,
    containment: { type: 'process' },
    filesystem: {
      readonlyPaths: [inputDirectory, commandInterpreter],
      readwritePaths: [outputDirectory],
    },
    // Omitted network and UI permissions remain denied.
    workingDirectory: inputDirectory,
    environment: {
      SystemRoot: systemRoot,
      LOCALAPPDATA: outputDirectory,
      TEMP: outputDirectory,
      TMP: outputDirectory,
    },
    timeoutMs: 30_000,
  };

  const result = await run(request);
  process.stdout.write(result.stdout);
  process.stderr.write(result.stderr);
  for (const warning of result.warnings) {
    console.error(warning);
  }

  if (result.timedOut) {
    throw new Error('The workload exceeded its timeout.');
  }

  console.log(`Sandbox exited with code ${result.exitCode}`);
  if (result.exitCode === 0) {
    process.stdout.write(readFileSync(outputFile, 'utf8'));
  }
  process.exitCode = result.exitCode;
} catch (error) {
  console.error(error);
  if (error instanceof MxcError && error.remediation) {
    console.error(error.remediation);
  }
  process.exitCode = 1;
}

次のようにアプリを実行します。

npx tsx sandbox.ts

錆

src\main.rsを次のように置き換えます。

use std::env;
use std::error::Error;
use std::fs;
use std::io::{self, Write};
use std::path::Path;

use mxc_sdk::v1::{self, ContainerRequest, Containment, FilesystemPolicy, WaitResult};

fn main() {
    match run() {
        Ok(code) => std::process::exit(code),
        Err(error) => {
            eprintln!("{error}");
            std::process::exit(1);
        }
    }
}

fn run() -> Result<i32, Box<dyn Error>> {
    if !cfg!(windows) {
        return Err("This example requires Windows.".into());
    }

    let support = v1::platform_support();
    if !support.is_supported
        || !support.available_methods.iter().any(|method| method == "processcontainer")
    {
        let reason = support
            .reason
            .unwrap_or_else(|| "Windows ProcessContainer is unavailable.".into());
        return Err(reason.into());
    }

    let system_root = env::var("SystemRoot")?;
    let project_directory = env::current_dir()?;
    let input_directory = project_directory.join("workspace").join("input");
    let output_directory = project_directory.join("workspace").join("output");
    let output_file = output_directory.join("result.txt");
    let command_interpreter = Path::new(&system_root).join("System32").join("cmd.exe");

    fs::create_dir_all(&input_directory)?;
    fs::create_dir_all(&output_directory)?;
    fs::write(input_directory.join("input.txt"), "Hello from MXC!\n")?;

    let input_path = input_directory.display().to_string();
    let output_path = output_directory.display().to_string();
    let request = ContainerRequest {
        containment: Containment::Process,
        filesystem: Some(FilesystemPolicy {
            readonly_paths: vec![input_path.clone(), command_interpreter.display().to_string()],
            readwrite_paths: vec![output_path.clone()],
            ..Default::default()
        }),
        // Omitted network and UI permissions remain denied.
        working_directory: Some(input_path),
        environment: Some(vec![
            ("SystemRoot".into(), system_root),
            ("LOCALAPPDATA".into(), output_path.clone()),
            ("TEMP".into(), output_path.clone()),
            ("TMP".into(), output_path),
        ]),
        timeout_ms: Some(30_000),
        ..ContainerRequest::new(format!(
            "\"{}\" /d /c type input.txt > \"{}\"",
            command_interpreter.display(),
            output_file.display()
        ))
    };

    let result = match v1::run(request, Default::default()) {
        Ok(result) => result,
        Err(error) => {
            eprintln!("{error}");
            if let Some(remediation) = &error.remediation {
                eprintln!("{remediation}");
            }
            return Ok(1);
        }
    };
    io::stdout().write_all(&result.stdout)?;
    io::stderr().write_all(&result.stderr)?;
    for warning in &result.warnings {
        eprintln!("{warning}");
    }

    let exit_code = match result.outcome {
        WaitResult::Exited(code) => code,
        WaitResult::TimedOut => return Err("The workload exceeded its timeout.".into()),
    };

    println!("Sandbox exited with code {exit_code}");
    if exit_code == 0 {
        print!("{}", fs::read_to_string(&output_file)?);
    }
    Ok(exit_code)
}

次のようにアプリを実行します。

cargo run

各バージョンは次の内容を出力します。

Sandbox exited with code 0
Hello from MXC!

workspace\output\result.txtを検査することもできます。

3. 拒否された操作を確認する

コマンドが読み取り専用入力ディレクトリへの書き込みを試みるように、出力ファイル宣言のみを変更します。

.NET

string outputFile = Path.Combine(inputDirectory, "blocked.txt");

TypeScript

const outputFile = join(inputDirectory, 'blocked.txt');

錆

let output_file = input_directory.join("blocked.txt");

ポリシーを変更せずに、アプリをもう一度実行してください。 アクセス拒否エラーと 0 以外の終了コードが想定され、新しい workspace\input\blocked.txt ファイルはありません。 元の出力ファイル宣言を復元し、許可された操作が引き続き成功することを確認します。

許可された実行が失敗した場合は、ホストのセットアップや構成のエラーと、リソースへのアクセス拒否を区別してください。 リソースへのアクセス拒否を調査するには、学習モードを使用してください。ポリシーの許可範囲が自動的に拡大されないようにしてください。

4. 例を調整する

サンプル コマンドと入力を信頼できる代表的なワークロードに置き換えてください。 必要なツールのバイナリ、ライブラリ、一時ファイル、出力ファイルを確認してください。 タスクに必要な場合にのみ、かつ選択したバックエンドが意図した制限を適用できる場合にのみ、ネットワークまたは UI へのアクセスを追加します。

すべてのターゲット ホストで許可された操作と拒否された操作をテストします。 学習モードを使用してポリシーを調整する場合は、記録されたアクセスを一つずつ確認し、最後に学習設定や監査設定を使用せず、制限を適用した状態で実行して検証してください。

任意: コーディングエージェントを使用する

ターゲット プラットフォーム、SDK の言語とバージョン、コマンド、必要なリソース、ライフサイクル、分離の目標をエージェントに指定します。 このプロンプトは、次のように調整できます。

Use the MXC Learn quickstart and the documentation for my installed SDK release.
Integrate this workload through the .NET, TypeScript, or Rust SDK used by this project.

First identify the command, target platforms, input and output paths, network
and UI requirements, and whether state must persist between commands.
Explain the containment choice and create the narrowest policy that fits.
Run both permitted and denied cases and report the effective permissions.

Do not execute the workload outside MXC to get around a failure. Ask for my
approval before expanding access, changing host settings, or using permissive
Learning Mode. Treat observed resource access as evidence, not automatic grants.

エージェントの前提条件と、それによって生じるポリシーを確認します。 エージェントは連携機能の実装を支援できますが、ワークロードに付与する権限の変更には、信頼できるホスト側のコードまたは担当者による承認が必要です。

次のステップ

• 永続的または特殊化されたバックエンドを使用する前に 、MXC アーキテクチャと包含モデル を確認します。
• MXC ポリシーを作成して検証する方法について説明します。
• MXC コンテインメント オプションとプラットフォームのサポートを比較します。
• 学習モードの完全なワークフローを確認します。
• MXC ポリシーの例を他のワークロードに合わせて調整します。
• MXC リリースで SDK パッケージとリリース ノートを確認できます。