Início rápido: Executar uma carga de trabalho com o SDK MXC

Use o SDK de .NET, TypeScript ou Rust para executar um comando no isolamento de processos do Windows. Cada exemplo cria uma entrada de exemplo, permite que a carga de trabalho a leia e concede acesso de escrita a uma pasta de saída separada. As permissões de rede e interface de utilizador continuam negadas.

A sua aplicação anfitriã cria a política e trata do resultado. O comando corre dentro do MXC; o resto da aplicação anfitriã não.

Os exemplos utilizam as APIs do SDK MXC 1.0 V1. Os SDKs V1 usam o esquema estável 1.0.0 internamente, por isso não especifica uma versão do esquema no pedido. Veja Escolher um esquema compatível.

Prerequisites

Precisas:

• Windows 11, versão 24H2 ou posterior, com um ambiente ProcessContainer suportado.
• Para C#, o SDK do .NET 8 ou posterior e o Microsoft.Mxc.Sdk pacote NuGet.
• Para o TypeScript, o npm, o pacote @microsoft/mxc-sdk e o Node.js 24.21.0 ou posterior na linha de lançamento do Node.js 24, ou o Node.js 26.8.0 ou posterior.
• Para Rust, uma cadeia de ferramentas Rust estável com as ferramentas de construção MSVC e a mxc-sdk crate. Veja Configure o seu ambiente de desenvolvimento Rust no Windows.
• Um diretório de trabalho gravável e PowerShell para os comandos de configuração.

As instruções utilizam os pacotes MXC 1.0 da NuGet.org, npm e crates.io. Não é necessária nenhuma compilação de origem MXC.

Verifique o suporte da plataforma antes de executar o exemplo. Uma versão do Windows suportada não garante que todas as funcionalidades opcionais estejam disponíveis.

Em alguns hosts, o MXC executa isolamento de processos numa camada de reserva baseada em AppContainer. Esse nível exige uma preparação única do disco do sistema e do dispositivo nulo, e a definição do dispositivo nulo é reposta a cada reinício. Quando falta preparação, a sonda do host do MXC devolve um aviso que indica o wxc-host-prep.exe subcomando para executar. O exemplo do TypeScript imprime estes avisos a partir de getPlatformSupport(), e também pode verificar um host executando wxc-exec.exe --probe. Como wxc-host-prep.exe requer aprovação do administrador, pede a um administrador para executar o comando recomendado em vez de o executar a partir da tua aplicação. Para mais detalhes, consulte Preparação do host.

1. Criar um projeto

.NET

Cria uma aplicação de consola e adiciona o pacote MXC da NuGet.org:

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

TypeScript

Crie um projeto Node.js, instale o MXC e adicione tsx para executar o exemplo do 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

Ferrugem

Crie um crate binário e adicione o crate MXC do crates.io:

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

2. Definir e executar a carga de trabalho

O isolamento de processos encaixa neste comando de curta duração porque necessita de ficheiros do anfitrião selecionados e sem ambiente persistente. Outras cargas de trabalho podem exigir um tipo de confinamento diferente.

O anfitrião cria workspace\input e workspace\output no diretório do projeto. O comando contido lê input.txt e escreve result.txt. Não recebe acesso de escrita ao seu diretório de entrada nem a outros ficheiros do projeto.

O anfitrião fornece um ambiente pequeno e explícito em vez de herdar as suas próprias variáveis. Quando fornecer um ambiente para uma carga de trabalho do Windows ProcessContainer, inclua tanto SystemRoot como LOCALAPPDATA. O MXC rejeita o pedido antes do lançamento se algum deles estiver em falta. O exemplo aponta LOCALAPPDATA, TEMP, e TMP para o diretório de saída concedido, de modo que ficheiros temporários e por utilizador permaneçam dentro da política.

.NET

Substitua Program.cs por:

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

Execute o aplicativo:

dotnet run

TypeScript

Crie sandbox.ts com:

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

Execute o aplicativo:

npx tsx sandbox.ts

Ferrugem

Substitua src\main.rs por:

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

Execute o aplicativo:

cargo run

Cada versão imprime:

Sandbox exited with code 0
Hello from MXC!

Também pode inspecionar workspace\output\result.txt.

3. Verificar uma operação negada

Altere apenas a declaração do ficheiro de saída para que o comando tente escrever no diretório de entrada apenas de leitura:

.NET

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

TypeScript

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

Ferrugem

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

Executa a aplicação novamente sem alterar a política. Espere um erro de acesso negado e um código de saída diferente de zero, sem ficheiro novo workspace\input\blocked.txt . Restaure a declaração original do ficheiro de saída e confirme que a operação permitida continua a ter êxito.

Se a execução permitida falhar, distinga os erros de instalação/configuração inicial do host ou de configuração de uma negação de recurso. Utilize o Modo de Aprendizagem para investigar a última; não alargue a política automaticamente.

4. Adapte o exemplo

Substitua o comando de exemplo e as entradas por uma carga de trabalho representativa de confiança. Revise binários de ferramentas, bibliotecas, ficheiros temporários e saídas obrigatórios. Adicionar acesso à rede ou à interface apenas quando a tarefa o exigir e quando o backend selecionado conseguir impor as restrições pretendidas.

Testar operações permitidas e recusadas em todos os hosts de destino. Quando usar o Modo Aprendizagem para refinar a política, reveja cada observação e termine com uma execução de aplicação sem definições de aprendizagem ou auditoria.

Opcional: usar um agente de codificação

Dê ao seu agente as plataformas-alvo, linguagem e versão do SDK, comandos, recursos necessários, ciclo de vida e objetivos de isolamento. Pode adaptar este prompt:

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.

Reveja as suposições do agente e a política resultante. Um agente pode ajudar na integração, mas código de host fiável ou uma pessoa deve aprovar alterações à autorização da carga de trabalho.

Passos seguintes

• Revise a arquitetura MXC e os modelos de contenção antes de usar backends persistentes ou especializados.
• Aprenda a criar e validar uma política MXC.
• Compare as opções de contenção MXC e o suporte da plataforma.
• Revise todo o fluxo de trabalho do Modo de Aprendizagem.
• Adapte os exemplos de políticas MXC a outras cargas de trabalho.
• Encontre pacotes SDK e notas de lançamento nas versões MXC.