Quickstart: Een workload uitvoeren met de MXC SDK

Gebruik de .NET, TypeScript of Rust SDK om een opdracht uit te voeren in Windows procesisolatie. In elk voorbeeld wordt een voorbeeldinvoer gemaakt, kan de workload deze lezen en wordt schrijftoegang verleend tot een afzonderlijke uitvoermap. Netwerk- en gebruikersinterfacemachtigingen zijn nog steeds geweigerd.

Uw host-app maakt de policy en verwerkt het resultaat. De opdracht wordt uitgevoerd in MXC; de rest van de host-app wordt dat niet.

In de voorbeelden worden de MXC 1.0 V1 SDK-API's gebruikt. De V1 SDK's maken intern gebruik van het stabiele 1.0.0 schema, zodat u geen schemaversie opgeeft in uw aanvraag. Zie Een compatibel schema kiezen.

Prerequisites

U hebt het volgende nodig:

• Windows 11 versie 24H2 of later met een ondersteunde ProcessContainer-omgeving.
• Voor C# hebt u de .NET 8 SDK of hoger en het Microsoft.Mxc.Sdk NuGet-pakket nodig.
• Voor TypeScript, npm, het @microsoft/mxc-sdk pakket en Node.js 24.21.0 of hoger in de releaseregel Node.js 24 of Node.js 26.8.0 of hoger.
• Voor Rust, een stabiele Rust-toolchain met de MSVC-buildhulpprogramma's en de mxc-sdk crate. Zie Uw Rust-ontwikkelomgeving instellen op Windows.
• Een beschrijfbare werkdirectory en PowerShell voor de installatieopdrachten.

In de instructies worden de MXC 1.0-pakketten van NuGet.org, npm en crates.io gebruikt. Er is geen MXC-bronbuild vereist.

Controleer de platformondersteuning voordat u het voorbeeld uitvoert. Een ondersteunde Windows-versie garandeert niet dat elke optionele functie beschikbaar is.

Op sommige hosts voert MXC procesisolatie uit in een op AppContainer gebaseerde terugvallaag. Deze laag vereist eenmalige voorbereiding van het systeemstation en het null-apparaat, en de instelling voor het null-apparaat wordt bij elke herstart opnieuw ingesteld. Wanneer de voorbereiding ontbreekt, retourneert de hosttest van MXC een waarschuwing die de wxc-host-prep.exe subopdracht noemt die moet worden uitgevoerd. In het TypeScript-voorbeeld worden deze waarschuwingen van getPlatformSupport() afgedrukt, en kunt u ook een host controleren door wxc-exec.exe --probe uit te voeren. Omdat voor wxc-host-prep.exe goedkeuring van de beheerder is vereist, moet u een beheerder de aanbevolen opdracht laten uitvoeren in plaats van deze uit te voeren vanuit uw app. Zie Host preparation voor details.

1. Een project maken

.NET

Maak een console-app en voeg het MXC-pakket toe vanuit NuGet.org:

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

TypeScript

Maak een Node.js-project, installeer MXC en voeg tsx toe om het TypeScript-voorbeeld uit te voeren:

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

Roest

Maak een binaire crate en voeg de MXC crate van crates.io toe:

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

2. Definieer en voer de workload uit

Procesisolatie past bij deze kortdurende opdracht omdat er geselecteerde hostbestanden en geen bewaarde omgeving nodig zijn. Voor andere workloads kan een ander insluitingstype zijn vereist.

De host maakt workspace\input en workspace\output onder de projectmap. De ingesloten opdracht leest input.txt en schrijft result.txt. Het ontvangt geen schrijftoegang tot de invoermap of toegang tot andere projectbestanden.

De host levert een kleine, expliciete omgeving in plaats van zijn eigen variabelen over te nemen. Wanneer u een omgeving opgeeft voor een Windows ProcessContainer-workload, neemt u zowel SystemRoot als LOCALAPPDATA op. MXC weigert het verzoek vóór de lancering als een van beide ontbreekt. De voorbeeldpunten LOCALAPPDATA, TEMP en TMP wijst naar de toegewezen uitvoermap, zodat tijdelijke bestanden en bestanden per gebruiker binnen het beleid blijven.

.NET

Vervangen Program.cs door:

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

De app uitvoeren:

dotnet run

TypeScript

Maak sandbox.ts met:

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

De app uitvoeren:

npx tsx sandbox.ts

Roest

Vervangen src\main.rs door:

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

De app uitvoeren:

cargo run

Elke versie print:

Sandbox exited with code 0
Hello from MXC!

U kunt ook workspace\output\result.txt inspecteren.

3. Controleer een geweigerde bewerking

Wijzig alleen de declaratie van het uitvoerbestand, zodat de opdracht probeert te schrijven naar de alleen-lezen invoermap:

.NET

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

TypeScript

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

Roest

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

Voer de app opnieuw uit zonder het beleid te wijzigen. Verwacht een fout met geweigerde toegang en een niet-nul afsluitcode, zonder nieuw workspace\input\blocked.txt bestand. Herstel de oorspronkelijke declaratie van het uitvoerbestand en bevestig dat de toegestane bewerking nog steeds slaagt.

Als de toegestane uitvoering mislukt, moet u hostinstellingen of configuratiefouten onderscheiden van een weigering van systeembronnen. Gebruik Leermodus om dat laatste te onderzoeken; breid het beleid niet automatisch uit.

4. Het voorbeeld aanpassen

Vervang de voorbeeldopdracht en invoer door een betrouwbare representatieve workload. Controleer de vereiste binaire hulpprogramma's, bibliotheken, tijdelijke bestanden en uitvoer. Voeg alleen netwerk- of gebruikersinterfacetoegang toe wanneer de taak deze vereist en de geselecteerde back-end kan de beoogde beperkingen afdwingen.

Test de toegestane en geweigerde bewerkingen op elke doelhost. Wanneer u de leermodus gebruikt om het beleid te verfijnen, controleert u elke observatie en sluit u af met een afdwingende uitvoering zonder instellingen voor leren of controleren.

Optioneel: een coderingsagent gebruiken

Geef uw agent de doelplatformen, sdk-taal en -versie, opdracht, vereiste resources, levenscyclus en isolatiedoelen. U kunt deze prompt aanpassen:

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.

Controleer de veronderstellingen en het resulterende beleid van de agent. Een agent kan helpen bij de integratie, maar vertrouwde hostcode of een persoon moet wijzigingen in de autorisatie van de workload goedkeuren.

Volgende stappen 

• Bekijk de MXC-architectuur en containmentmodellen voordat u permanente of gespecialiseerde back-ends gebruikt.
• Leer hoe u een MXC-beleid ontwerpt en valideert.
• Vergelijk MXC-insluitingsopties en platformondersteuning.
• Bekijk de volledige werkstroom van de leermodus.
• Pas de MXC-beleidsvoorbeelden voor andere workloads aan.
• Zoek SDK-pakketten en releaseopmerkingen in MXC-releases.