Guida introduttiva: Eseguire un carico di lavoro con MXC SDK

Usare .NET, TypeScript o Rust SDK per eseguire un comando con isolamento del processo di Windows. Ogni esempio crea un input di esempio, consente al carico di lavoro di leggerlo e concede l'accesso in scrittura a una cartella di output separata. Le autorizzazioni di rete e dell'interfaccia utente rimangono negate.

L'app host crea il criterio e gestisce il risultato. Il comando viene eseguito all'interno di MXC; il resto dell'app host non viene eseguito al suo interno.

Gli esempi usano le API MXC 1.0 V1 SDK. Gli SDK V1 usano internamente lo schema stabile 1.0.0 , quindi non si specifica una versione dello schema nella richiesta. Vedere Scegliere uno schema compatibile.

Prerequisites

È necessario:

Windows 11 versione 24H2 o successiva con un ambiente ProcessContainer supportato.
Per C#, sono necessari SDK .NET 8 o versione successiva e il Microsoft.Mxc.Sdk pacchetto NuGet.
Per TypeScript, npm, il pacchetto @microsoft/mxc-sdk e Node.js 24.21.0 o versione successiva nel ramo 24 di Node.js o Node.js 26.8.0 o versione successiva.
Per Rust, una toolchain stabile di Rust con gli strumenti di compilazione MSVC e il crate mxc-sdk. Vedi Configurare l'ambiente di sviluppo Rust su Windows.
Directory di lavoro scrivibile e PowerShell per i comandi di installazione.

Le istruzioni usano i pacchetti MXC 1.0 da NuGet.org, npm e crates.io. Non è necessaria alcuna build sorgente MXC.

Controllare il supporto della piattaforma prima di eseguire l'esempio. Una versione di Windows supportata non garantisce che tutte le funzionalità facoltative siano disponibili.

In alcuni sistemi host MXC esegue l'isolamento del processo in un livello di fallback basato su AppContainer. Tale livello richiede una preparazione una tantum dell'unità di sistema e del dispositivo Null e l'impostazione null-device viene reimpostata a ogni riavvio. Quando manca la preparazione, il probe host di MXC restituisce un avviso che riporta il sottocomando wxc-host-prep.exe da eseguire. L'esempio TypeScript stampa questi avvisi da getPlatformSupport()ed è anche possibile controllare un host eseguendo wxc-exec.exe --probe. Poiché wxc-host-prep.exe richiede l'approvazione dell'amministratore, chiedere a un amministratore di eseguire il comando consigliato anziché eseguirlo tramite la tua app. Per informazioni dettagliate, vedere Preparazione host.

1. Creare un progetto

Creare un'app console e aggiungere il pacchetto MXC da NuGet.org:

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

Creare un progetto Node.js, installare MXC e aggiungere tsx per eseguire l'esempio 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

Creare un crate binario e aggiungere il crate MXC da crates.io:

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

2. Definire ed eseguire il carico di lavoro

L'isolamento del processo si adatta a questo comando di breve durata perché richiede file host selezionati e senza mantenere alcun ambiente. Altri carichi di lavoro possono richiedere un tipo di contenitore diverso.

L'host crea workspace\input e workspace\output sotto la directory del progetto. Il comando contenuto legge input.txt e scrive result.txt. Non riceve l'accesso in scrittura alla directory di input o l'accesso ad altri file di progetto.

L'host fornisce un ambiente piccolo ed esplicito invece di ereditare le proprie variabili. Quando si specifica un ambiente per un carico di lavoro ProcessContainer Windows, includere sia SystemRoot che LOCALAPPDATA. MXC rifiuta la richiesta prima dell'avvio se ne manca una. Nell'esempio punta LOCALAPPDATA, TEMP e TMP alla directory di output concessa in modo che i file temporanei e per utente rimangano all'interno della policy.

Sostituire Program.cs con:

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

Eseguire l'app:

dotnet run

Creare sandbox.ts con:

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

Eseguire l'app:

npx tsx sandbox.ts

Sostituire src\main.rs con:

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

Eseguire l'app:

cargo run

Ogni versione stampa:

Sandbox exited with code 0
Hello from MXC!

È anche possibile controllare workspace\output\result.txt.

3. Verificare un'operazione negata

Modificare solo la dichiarazione del file di output in modo che il comando tenti di scrivere nella directory di input di sola lettura:

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

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

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

Eseguire di nuovo l'app senza modificare il criterio. Si prevede un errore di accesso negato e un codice di uscita diverso da zero, senza un nuovo workspace\input\blocked.txt file. Ripristinare la dichiarazione del file di output originale e verificare che l'operazione consentita abbia ancora esito positivo.

Se l'esecuzione consentita non riesce, distinguere la configurazione dell'host o gli errori di configurazione da un rifiuto della risorsa. Usa Learning Mode per analizzare il secondo; non ampliare automaticamente la policy.

4. Adattare l'esempio

Sostituire il comando di esempio e gli input con un carico di lavoro rappresentativo attendibile. Esaminare i file binari, le librerie, i file temporanei e gli output richiesti dello strumento. Aggiungere l'accesso alla rete o all'interfaccia utente solo quando l'attività lo richiede e il back-end selezionato può applicare le restrizioni previste.

Testare le operazioni consentite e negate in ogni host di destinazione. Quando si usa la modalità di apprendimento per perfezionare il criterio, esaminare ogni osservazione e terminare con un'esecuzione di applicazione senza impostazioni di apprendimento o audit.

Facoltativo: usare un agente di codifica

Assegnare all'agente le piattaforme di destinazione, il linguaggio e la versione dell'SDK, il comando, le risorse necessarie, il ciclo di vita e gli obiettivi di isolamento. È possibile adattare questa richiesta:

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.

Esaminare i presupposti dell'agente e la policy risultante. Un agente può supportare l'integrazione, ma il codice host attendibile o una persona deve approvare le modifiche ai permessi del carico di lavoro.

Passaggi successivi

Esaminare l'architettura e i modelli di contenimento MXC prima di usare back-end persistenti o specializzati.
Informazioni su come creare e convalidare una policy MXC.
Confrontare le opzioni di contenimento MXC e il supporto della piattaforma.
Esaminare il flusso di lavoro completo della modalità di apprendimento.
Adattare gli esempi di criteri MXC ad altri carichi di lavoro.
Trovare pacchetti SDK e note sulla versione nelle versioni MXC.

Commenti e suggerimenti

Questa pagina è stata utile?

Ultimo aggiornamento: 2026-10-27

Guida introduttiva: Eseguire un carico di lavoro con MXC SDK

Prerequisites

1. Creare un progetto

2. Definire ed eseguire il carico di lavoro

3. Verificare un'operazione negata

4. Adattare l'esempio

Facoltativo: usare un agente di codifica

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive