Hızlı Başlangıç: MXC SDK ile iş yükü çalıştırma

Windows işlem yalıtımında bir komut çalıştırmak için .NET, TypeScript veya Rust SDK'sını kullanın. Her örnek bir örnek giriş oluşturur, iş yükünün bu örnek girişi okumasına izin verir ve ayrı bir çıkış klasörüne yazma erişimi verir. Ağ ve kullanıcı arabirimi izinleri reddedilmiş durumda kalır.

Ana uygulamanız politikayı oluşturur ve sonucu işler. Komut MXC içinde çalışır; konak uygulamasının geri kalanı bunu yapmaz.

Örneklerde MXC 1.0 V1 SDK API'leri kullanılır. V1 SDK'ları kararlı 1.0.0 şemayı dahili olarak kullanır, bu nedenle isteğinizde bir şema sürümü belirtmezsiniz. Bkz. Uyumlu bir şema seçin.

Prerequisites

Şunlara sahip olmanız gerekir:

• desteklenen bir ProcessContainer ortamıyla Windows 11, sürüm 24H2 veya üzeri.
• C# için .NET 8 SDK’sı veya üzeri ve Microsoft.Mxc.Sdk NuGet paketi gerekir.
• TypeScript, npm, @microsoft/mxc-sdk paketi ve Node.js 24 sürüm satırında Node.js 24.21.0 veya üzeri ya da Node.js 26.8.0 veya üzeri için.
• Rust için, MSVC derleme araçları ve mxc-sdk crate ile kararlı bir Rust araç zinciri. Bkz.: Windows’ta Rust geliştirme ortamınızı ayarlama.
• Kurulum komutları için yazılabilir bir çalışma dizini ve PowerShell.

Yönergelerde NuGet.org, npm ve crates.io MXC 1.0 paketleri kullanılır. MXC kaynak derlemesi gerekmez.

Örneği çalıştırmadan önce platform desteğini denetleyin. Desteklenen bir Windows sürümü, isteğe bağlı her özelliğin kullanılabilir olduğunu garanti etmez.

Bazı konaklarda MXC, AppContainer tabanlı bir geri dönüş katmanında işlem yalıtımı çalıştırır. Bu katman için sistem sürücüsünün ve null cihazın tek seferlik hazırlanması gerekir ve null cihaz ayarı her yeniden başlatmada sıfırlanır. Hazırlık eksik olduğunda, MXC'nin host probe'u, wxc-host-prep.exe alt komutunu çalıştırmanızı söyleyen bir uyarı döndürür. TypeScript örneği bu uyarıları getPlatformSupport() kaynağından yazdırır ve wxc-exec.exe --probe komutunu çalıştırarak bir ana bilgisayarı da kontrol edebilirsiniz. wxc-host-prep.exe yönetici onayı gerektirdiğinden, bir yöneticinin önerilen komutu uygulamanızdan çalıştırmak yerine çalıştırmasını sağlayın. Ayrıntılar için bkz. Ana bilgisayar hazırlığı.

1. Proje oluşturma

.NET

Bir konsol uygulaması oluşturun ve NuGet.org MXC paketini ekleyin:

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

TypeScript

Bir Node.js projesi oluşturun, MXC'yi yükleyin ve TypeScript örneğini çalıştırmak için tsx ekleyin:

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

Bir binary crate oluşturun ve crates.io'dan MXC crate'ini ekleyin:

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

2. İş yükünü tanımlama ve çalıştırma

İşlem yalıtımı, seçili konak dosyalarına ihtiyaç duyduğu ve kalıcı bir ortam gerektirmediği için bu kısa süreli komuta uyar. Diğer iş yükleri farklı bir kapsayıcı türü gerektirebilir.

Ana bilgisayar, proje dizininin altında workspace\output ve workspace\input oluşturur. Bu komut input.txt öğesini okur ve result.txt öğesine yazar. Kendi giriş dizinine yazma erişimi veya diğer proje dosyalarına erişim almaz.

Ana bilgisayar, kendi değişkenlerini devralmak yerine küçük, açık bir ortam sağlar. Windows ProcessContainer iş yükü için bir ortam sağladığınızda hem LOCALAPPDATA hem de SystemRoot ekleyin. MXC, ikisinden herhangi biri eksikse başlatmadan önce isteği reddeder. Örnek, geçici ve kullanıcı başına dosyaların ilke içinde kalması için LOCALAPPDATA, TMP ve TEMP noktalarını verilen çıkış dizinine işaret eder.

.NET

şununla değiştirin 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;
}

Uygulamayı çalıştırın:

dotnet run

TypeScript

sandbox.ts oluşturmak için:

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

Uygulamayı çalıştırın:

npx tsx sandbox.ts

Rust

şununla değiştirin 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)
}

Uygulamayı çalıştırın:

cargo run

Her sürüm yazdırır:

Sandbox exited with code 0
Hello from MXC!

Ayrıca workspace\output\result.txt öğesini de inceleyebilirsiniz.

3. Reddedilen bir işlemi doğrulayın

Komutun salt okunur giriş dizinine yazmayı denemesi için yalnızca çıkış dosyası bildirimini değiştirin:

.NET

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

TypeScript

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

Rust

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

İlkeyi değiştirmeden uygulamayı yeniden çalıştırın. Yeni workspace\input\blocked.txt dosyası oluşmadan, erişim reddedildi hatası ve sıfır olmayan bir çıkış kodu bekleyebilirsiniz. Özgün çıkış dosyası bildirimini geri yükleyin ve izin verilen işlemin hâlâ başarıyla gerçekleştiğini doğrulayın.

İzin verilen çalıştırma başarısız olursa, konak kurulumu veya yapılandırma hatalarını kaynak reddinden ayırt edin. İkincisini araştırmak için Öğrenme Modu'nu kullanın; ilkeyi otomatik olarak genişletmeyin.

4. Örneği uyarlayın

Örnek komutu ve girişleri güvenilir bir temsilci iş yüküyle değiştirin. Gerekli aracın ikili dosyalarını, kitaplıkları, geçici dosyaları ve çıkışları gözden geçirin. Ağ veya kullanıcı arabirimi erişimini yalnızca görev gerektirdiğinde ve seçilen arka uç istenen kısıtlamaları uygulayabiliyorsa ekleyin.

Her hedef konakta izin verilen ve reddedilen işlemleri test edin. İlkeyi geliştirmek için Öğrenme Modu'nu kullandığınızda, her gözlemi gözden geçirin ve öğrenme veya denetim ayarları olmadan bir zorlama çalıştırmasıyla tamamlayın.

İsteğe bağlı: kodlama aracını kullan

Aracınıza hedef platformları, SDK dilini ve sürümünü, komutunu, gerekli kaynakları, yaşam döngüsünü ve yalıtım hedeflerini verin. Bu istemi uyarlayabilirsiniz:

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.

Ajanın varsayımlarını ve sonuçta ortaya çıkan politikasını gözden geçirin. Bir aracı, tümleştirmeye yardımcı olabilir, ancak güvenilen konak kodu veya bir kişi iş yükünün yetkilerinde yapılan değişiklikleri onaylamalıdır.

Sonraki Adımlar

• Kalıcı veya özelleştirilmiş arka uçları kullanmadan önce MXC mimarisini ve kapsülleme modellerini gözden geçirin.
• MXC ilkesi yazmayı ve doğrulamayı öğrenin.
• MXC kapsama seçeneklerini ve platform desteğini karşılaştırın.
• Öğrenme Modu iş akışının tamamını gözden geçirin.
• MXC ilke örneklerini diğer iş yüklerine uyarlayın.
• MXC sürümlerinde SDK paketlerini ve sürüm notlarını bulun.