Mulai cepat: Menjalankan beban kerja dengan MXC SDK

Gunakan SDK .NET, TypeScript, atau Rust untuk menjalankan perintah dalam isolasi proses Windows. Setiap contoh membuat input sampel, memungkinkan workload membacanya, dan memberikan akses tulis ke folder output terpisah. Izin jaringan dan UI tetap ditolak.

Aplikasi host Anda membuat kebijakan dan menangani hasilnya. Perintah berjalan di dalam MXC; bagian lain dari aplikasi host tidak.

Contohnya menggunakan API SDK MXC 1.0 V1. SDK V1 menggunakan skema stabil 1.0.0 secara internal, sehingga Anda tidak perlu menentukan versi skema dalam permintaan Anda. Lihat Pilih skema yang kompatibel.

Prerequisites

Kamu butuh:

• Windows 11, versi 24H2 atau yang lebih baru, dengan lingkungan ProcessContainer yang didukung.
• Untuk C#, SDK .NET 8 atau yang lebih baru dan paket NuGet Microsoft.Mxc.Sdk.
• Untuk TypeScript, npm, paket @microsoft/mxc-sdk, dan Node.js 24.21.0 atau yang lebih baru di lini rilis Node.js 24, atau Node.js 26.8.0 atau yang lebih baru.
• Untuk Rust, toolchain Rust yang stabil dengan alat build MSVC, dan mxc-sdk crate. Lihat Menyiapkan lingkungan pengembangan Rust Anda di Windows.
• Direktori kerja yang dapat ditulis dan PowerShell untuk perintah penyiapan.

Instruksi menggunakan paket MXC 1.0 dari NuGet.org, npm, dan crates.io. Tidak diperlukan build sumber MXC.

Periksa dukungan platform sebelum Anda menjalankan contoh. Versi Windows yang didukung tidak menjamin bahwa setiap fitur opsional tersedia.

Pada beberapa host, MXC menjalankan isolasi proses di tingkat fallback berbasis AppContainer. Tingkat tersebut membutuhkan persiapan satu kali untuk drive sistem dan perangkat null, dan pengaturan perangkat null diatur ulang setiap kali sistem dimulai ulang. Jika persiapan belum dilakukan, pemeriksaan host MXC mengembalikan peringatan yang memberi nama wxc-host-prep.exe subperintah untuk dijalankan. Contoh TypeScript mencetak peringatan ini dari getPlatformSupport(), dan Anda juga dapat memeriksa host dengan menjalankan wxc-exec.exe --probe. Karena wxc-host-prep.exe memerlukan persetujuan administrator, minta administrator menjalankan perintah yang direkomendasikan daripada menjalankannya dari aplikasi Anda. Untuk detailnya, lihat Persiapan host.

1. Buat proyek

.NET

Buat aplikasi konsol dan tambahkan paket MXC dari NuGet.org:

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

TypeScript

Buat proyek Node.js, instal MXC, dan tambahkan tsx untuk menjalankan contoh TypeScript:

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

Rust

Buat crate biner dan tambahkan crate MXC dari crates.io:

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

2. Tentukan dan jalankan beban kerja

Isolasi proses cocok dengan perintah berumur pendek ini karena membutuhkan file host yang dipilih dan tanpa lingkungan yang dipertahankan. Beban kerja lain dapat memerlukan jenis containment yang berbeda.

Host membuat workspace\input dan workspace\output di bawah direktori proyek. Perintah yang terkandung membaca input.txt dan menulis result.txt. Ini tidak menerima akses tulis ke direktori input atau akses ke file proyek lain.

Host menyediakan lingkungan yang kecil dan eksplisit alih-alih mewarisi variabel miliknya sendiri. Saat Anda menyediakan lingkungan untuk beban kerja ProcessContainer Windows, sertakan keduanya, SystemRoot dan LOCALAPPDATA. MXC menolak permintaan sebelum diluncurkan jika salah satu dari keduanya tidak ada. Contoh mengarahkan LOCALAPPDATA, TEMP, dan TMP ke direktori output yang diizinkan sehingga file sementara dan per pengguna tetap sesuai dengan kebijakan.

.NET

Ganti Program.cs dengan:

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

Jalankan aplikasi:

dotnet run

TypeScript

Buat sandbox.ts dengan:

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

Jalankan aplikasi:

npx tsx sandbox.ts

Rust

Ganti src\main.rs dengan:

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

Jalankan aplikasi:

cargo run

Setiap versi mencetak:

Sandbox exited with code 0
Hello from MXC!

Anda juga dapat memeriksa workspace\output\result.txt.

3. Verifikasi operasi yang ditolak

Ubah hanya deklarasi file output sehingga perintah mencoba menulis ke direktori input baca-saja:

.NET

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

TypeScript

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

Rust

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

Jalankan aplikasi lagi tanpa mengubah kebijakan. Harapkan kesalahan akses ditolak dan kode keluar bukan nol, tanpa file workspace\input\blocked.txt baru. Pulihkan deklarasi file output asli dan konfirmasikan bahwa operasi yang diizinkan masih berhasil.

Jika proses yang diizinkan gagal, bedakan pengaturan host atau kesalahan konfigurasi dari penolakan sumber daya. Gunakan Mode Pembelajaran untuk menyelidiki yang terakhir; jangan memperluas kebijakan secara otomatis.

4. Sesuaikan contoh

Ganti perintah sampel dan input dengan beban kerja perwakilan tepercaya. Harus meninjau biner alat, pustaka, file sementara, dan output. Tambahkan akses jaringan atau UI hanya ketika tugas memerlukannya dan backend yang dipilih dapat memberlakukan pembatasan yang dimaksudkan.

Uji operasi yang diizinkan dan ditolak pada setiap host target. Saat Anda menggunakan Mode Pembelajaran untuk menyempurnakan kebijakan, tinjau setiap pengamatan dan selesaikan dengan jalankan penegakan tanpa setelan mode pembelajaran maupun audit.

Opsional: gunakan coding agent

Beri agen Anda platform target, bahasa dan versi SDK, perintah, sumber daya yang diperlukan, siklus hidup, dan tujuan isolasi. Anda dapat menyesuaikan perintah ini:

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.

Tinjau asumsi agen dan kebijakan yang dihasilkan. Agen dapat membantu integrasi, tetapi kode host tepercaya atau seseorang harus menyetujui perubahan pada otorisasi beban kerja.

Langkah berikutnya

• Tinjau arsitektur MXC dan model containment sebelum menggunakan backend persisten atau khusus.
• Pelajari cara menulis dan memvalidasi kebijakan MXC.
• Bandingkan opsi containment MXC dan dukungan platform.
• Tinjau alur kerja Mode Pembelajaran lengkap.
• Sesuaikan contoh kebijakan MXC dengan beban kerja lain.
• Temukan paket SDK dan catatan rilis dalam rilis MXC.