Inicio rápido: Ejecución de una carga de trabajo con el SDK de MXC

Use el SDK de .NET, TypeScript o Rust para ejecutar un comando en aislamiento de procesos de Windows. Cada ejemplo crea una entrada de muestra, permite a la carga de trabajo leerla y concede acceso de escritura a una carpeta de salida independiente. Los permisos de red y de interfaz de usuario permanecen denegados.

La aplicación host crea la directiva y controla el resultado. El comando se ejecuta dentro de MXC; el resto de la aplicación host no.

En los ejemplos se usan las API del SDK de MXC 1.0 V1. Los SDK V1 usan el esquema estable 1.0.0 internamente, por lo que no se especifica una versión de esquema en la solicitud. Consulte Elegir un esquema compatible.

Prerequisites

Necesitas:

• Windows 11, versión 24H2 o posterior, con un entorno ProcessContainer compatible.
• Para C#, se requiere el SDK de .NET 8 o posterior y el paquete Microsoft.Mxc.Sdk NuGet.
• Para TypeScript, npm, el @microsoft/mxc-sdk paquete y Node.js 24.21.0 o posterior en la línea de versión de Node.js 24 o Node.js 26.8.0 o posterior.
• Para Rust, una cadena de herramientas estable de Rust con las herramientas de compilación de MSVC y el mxc-sdk crate. Consulte Configuración del entorno de desarrollo de Rust en Windows.
• Directorio de trabajo grabable y PowerShell para los comandos de instalación.

Las instrucciones usan los paquetes MXC 1.0 de NuGet.org, npm y crates.io. No se requiere ninguna compilación fuente de MXC.

Compruebe la compatibilidad con la plataforma antes de ejecutar el ejemplo. Una versión de Windows compatible no garantiza que todas las características opcionales estén disponibles.

En algunos hosts, MXC ejecuta el aislamiento de procesos en un nivel de reserva basado en AppContainer. Ese nivel necesita una preparación única de la unidad del sistema y el dispositivo NULL, y la configuración del dispositivo NULL se restablece en cada reinicio. Cuando falta la preparación, el sondeo de host de MXC devuelve una advertencia que indica el subcomando wxc-host-prep.exe que se debe ejecutar. En el ejemplo de TypeScript se imprimen estas advertencias de getPlatformSupport()y también puede comprobar un host ejecutando wxc-exec.exe --probe. Dado que wxc-host-prep.exe requiere aprobación de administrador, haga que un administrador ejecute el comando recomendado en lugar de ejecutarlo desde la aplicación. Para obtener más información, consulte Preparación del host.

1. Crear un proyecto

.NET

Cree una aplicación de consola y agregue el paquete MXC desde NuGet.org:

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

TypeScript

Cree un proyecto de Node.js, instale MXC y agregue tsx para ejecutar el ejemplo de 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

Óxido

Cree un crate binario y agregue el crate MXC desde crates.io:

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

2. Definir y ejecutar la carga de trabajo

El aislamiento de procesos se ajusta a este comando de corta duración porque necesita archivos host seleccionados y ningún entorno retenido. Otras cargas de trabajo pueden requerir un tipo de contención diferente.

El host crea workspace\input y workspace\output debajo del directorio del proyecto. El comando contenido lee input.txt y escribe result.txt. No recibe acceso de escritura a su directorio de entrada ni acceso a otros archivos de proyecto.

El host suministra un entorno pequeño y explícito en lugar de heredar sus propias variables. Al proporcionar un entorno para una carga de trabajo processContainer de Windows, incluya tanto SystemRoot como LOCALAPPDATA. MXC rechaza la solicitud antes de iniciarse si falta cualquiera de los dos. El ejemplo apunta LOCALAPPDATA, TEMP y TMP al directorio de salida concedido para que los archivos temporales y por usuario permanezcan dentro de la directiva.

.NET

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

Ejecute la aplicación:

dotnet run

TypeScript

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

Ejecute la aplicación:

npx tsx sandbox.ts

Óxido

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

Ejecute la aplicación:

cargo run

Cada versión imprime:

Sandbox exited with code 0
Hello from MXC!

También puede inspeccionar workspace\output\result.txt.

3. Verificar una operación denegada

Cambie solo la declaración del archivo de salida para que el comando intente escribir en el directorio de entrada de solo lectura:

.NET

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

TypeScript

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

Óxido

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

Vuelva a ejecutar la aplicación sin cambiar la directiva. Espere un error de acceso denegado y un código de salida distinto de cero, sin ningún archivo workspace\input\blocked.txt nuevo. Restaure la declaración del archivo de salida original y confirme que la operación permitida sigue funcionando correctamente.

Si la ejecución permitida falla, distinga los errores de configuración del host o de configuración de una denegación de recursos. Use Learning Mode para investigar lo segundo; no amplíe la directiva automáticamente.

4. Adapta el ejemplo

Reemplace el comando de ejemplo y las entradas por una carga de trabajo representativa de confianza. Se requiere revisar los archivos binarios de herramientas, las bibliotecas, los archivos temporales y las salidas. Agregue acceso a la red o a la interfaz de usuario solo cuando la tarea lo requiera y el back-end seleccionado pueda aplicar las restricciones previstas.

Pruebe las operaciones permitidas y denegadas en cada host de destino. Cuando use el modo de aprendizaje para refinar la directiva, revise cada observación y finalice con una ejecución de aplicación sin aprendizaje ni configuración de auditoría.

Opcional: usar un agente de programación

Asigne al agente las plataformas de destino, el lenguaje del SDK y la versión, el comando, los recursos necesarios, el ciclo de vida y los objetivos de aislamiento. Puede adaptar este mensaje:

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.

Revise las suposiciones del agente y la política resultante. Un agente puede ayudar con la integración, pero el código del host de confianza o una persona debe aprobar los cambios en la autoridad de la carga de trabajo.

Pasos siguientes

• Revise la arquitectura MXC y los modelos de contención antes de usar back-end persistentes o especializados.
• Aprenda a crear y validar una directiva MXC.
• Compare las opciones de contención y la compatibilidad de plataforma de MXC.
• Revise el flujo de trabajo completo del modo de aprendizaje.
• Adapte los ejemplos de directivas MXC a otras cargas de trabajo.
• Busque paquetes de SDK y notas de la versión en las versiones MXC.