Szybki start: uruchamianie obciążenia roboczego przy użyciu zestawu MXC SDK

Użyj zestawu SDK .NET, TypeScript lub Rust, aby uruchomić polecenie w trybie izolacji procesów systemu Windows. Każdy przykład tworzy przykładowe dane wejściowe, umożliwia obciążeniu odczyt tych danych i udziela dostępu do zapisu w oddzielnym folderze wyjściowym. Uprawnienia sieci i interfejsu użytkownika nadal nie zostały przyznane.

Aplikacja hosta tworzy zasadę i obsługuje wynik. Polecenie jest uruchamiane wewnątrz MXC; pozostała część aplikacji hosta nie.

W przykładach użyto interfejsów API zestawu SDK MXC 1.0 V1. Zestawy SDK w wersji 1 używają stabilnego 1.0.0 schematu wewnętrznie, więc nie określasz wersji schematu w żądaniu. Zobacz Wybierz zgodny schemat.

Prerequisites

Potrzebujesz:

• Windows 11 w wersji 24H2 lub nowszej z obsługiwanym środowiskiem ProcessContainer.
• W przypadku języka C# wymagane są zestaw SDK .NET 8 lub nowszy oraz pakiet NuGet Microsoft.Mxc.Sdk.
• W przypadku języka TypeScript, npm, pakietu @microsoft/mxc-sdk i Node.js 24.21.0 lub nowszego w wierszu wydania Node.js 24 lub Node.js 26.8.0 lub nowszym.
• W przypadku języka Rust: stabilny łańcuch narzędzi Rust z narzędziami kompilacji MSVC i crate mxc-sdk. Zobacz Konfigurowanie środowiska deweloperskiego Rust w Windows.
• Zapisywalny katalog roboczy i program PowerShell dla poleceń konfiguracji.

W instrukcjach użyto pakietów MXC 1.0 z NuGet.org, npm i crates.io. Nie jest wymagana żadna kompilacja źródłowa MXC.

Przed uruchomieniem przykładu sprawdź obsługę platformy . Obsługiwana wersja Windows nie gwarantuje dostępności każdej opcjonalnej funkcji.

Na niektórych hostach mxC uruchamia izolację procesów w warstwie rezerwowej opartej na AppContainer. Ta warstwa wymaga jednorazowego przygotowania dysku systemowego i urządzenia null, a ustawienie null-device resetuje się przy każdym ponownym uruchomieniu. W przypadku braku przygotowania sonda hosta MXC zwraca ostrzeżenie, które wskazuje podpolecenie wxc-host-prep.exe, które należy uruchomić. Przykład języka TypeScript wyświetla te ostrzeżenia z getPlatformSupport()elementu , a także możesz sprawdzić hosta, uruchamiając polecenie wxc-exec.exe --probe. Ponieważ wxc-host-prep.exe wymaga zatwierdzenia przez administratora, poproś administratora o uruchomienie zalecanego polecenia, zamiast uruchamiać je z poziomu aplikacji. Aby uzyskać szczegółowe informacje, zobacz Przygotowanie hosta.

1. Tworzenie projektu

.NET

Utwórz aplikację konsolową i dodaj pakiet MXC z NuGet.org:

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

TypeScript

Utwórz projekt Node.js, zainstaluj aplikację MXC i dodaj tsx, aby uruchomić przykład języka 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

Rdza

Utwórz binarny crate i dodaj crate MXC z crates.io:

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

2. Zdefiniuj i uruchom obciążenie robocze

Izolacja procesu pasuje do tego krótkotrwałego polecenia, ponieważ wymaga wybranych plików hosta i nie potrzebuje zachowanego środowiska. Inne obciążenia mogą wymagać innego typu hermetyzacji.

Host tworzy workspace\input i workspace\output w katalogu projektu. Zawarte polecenie odczytuje input.txt i zapisuje result.txt. Nie otrzymuje dostępu do zapisu do katalogu wejściowego ani dostępu do innych plików projektu.

Host dostarcza małe, jawne środowisko zamiast dziedziczyć własne zmienne. W przypadku dostarczania środowiska dla obciążenia Windows ProcessContainer należy uwzględnić zarówno SystemRoot, jak i LOCALAPPDATA. MXC odrzuca żądanie przed uruchomieniem, jeśli brakuje jednego z nich. W przykładzie elementy LOCALAPPDATA, TEMP i TMP wskazują na udzielony katalog wyjściowy, aby pliki tymczasowe i pliki poszczególnych użytkowników pozostawały zgodnie z zasadami polityki.

.NET

Zastąp ciąg Program.cs ciągiem :

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

Uruchom aplikację:

dotnet run

TypeScript

Utwórz sandbox.ts za pomocą:

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

Uruchom aplikację:

npx tsx sandbox.ts

Rdza

Zastąp ciąg src\main.rs ciągiem :

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

Uruchom aplikację:

cargo run

Każda wersja drukuje:

Sandbox exited with code 0
Hello from MXC!

Możesz również sprawdzić workspace\output\result.txt.

3. Sprawdź odrzuconą operację

Zmień tylko deklarację pliku wyjściowego, aby polecenie próbowało zapisać w katalogu wejściowym tylko do odczytu:

.NET

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

TypeScript

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

Rdza

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

Ponownie uruchom aplikację bez zmiany polityki. Oczekuj błędu odmowy dostępu i niezerowego kodu zakończenia, bez nowego pliku workspace\input\blocked.txt Przywróć oryginalną deklarację pliku wyjściowego i upewnij się, że dozwolona operacja nadal kończy się pomyślnie.

Jeśli dozwolone uruchomienie zakończy się niepowodzeniem, odróżnij błędy konfiguracji hosta od odmowy dostępu do zasobów. Użyj Learning Mode, aby zbadać ten ostatni; nie rozszerzaj zasady automatycznie.

4. Dostosuj przykład

Zastąp przykładowe polecenie i dane wejściowe wiarygodnym, reprezentatywnym obciążeniem roboczym. Przejrzyj wymagane pliki binarne narzędzi, biblioteki, pliki tymczasowe i dane wyjściowe. Dodaj dostęp do sieci lub interfejsu użytkownika tylko wtedy, gdy zadanie tego wymaga, a wybrany backend może wymusić zamierzone ograniczenia.

Przetestuj dozwolone i zabronione operacje na każdym hoście docelowym. Gdy używasz trybu uczenia do uściślania zasad, przejrzyj każdą obserwację i zakończ, uruchamiając tryb wymuszania bez uczenia się lub ustawień inspekcji.

Opcjonalnie: użyj agenta kodowania

Nadaj agentowi platformy docelowe, język i wersję zestawu SDK, polecenie, wymagane zasoby, cykl życia i cele izolacji. Ten prompt można dostosować:

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.

Przejrzyj założenia agenta i wynikową politykę. Agent może pomóc w integracji, ale zaufany kod hosta lub osoba musi zatwierdzić zmiany w uprawnieniach obciążenia roboczego.

Następne kroki

• Przed użyciem trwałych lub wyspecjalizowanych zapleczy zapoznaj się z architekturą MXC i modelami hermetyzacji.
• Dowiedz się, jak tworzyć i weryfikować zasady MXC.
• Porównanie opcji zawierania MXC i obsługę platform.
• Przejrzyj pełny przepływ pracy w trybie uczenia.
• Dostosuj przykłady zasad MXC do innych obciążeń.
• Znajdź pakiety zestawu SDK i informacje o wydaniu w wersjach MXC.