Rychlý start: Spuštění úlohy pomocí sady MXC SDK

Pomocí sady .NET, TypeScript nebo Rust SDK spusťte příkaz v izolaci procesů systému Windows. Každý příklad vytvoří ukázkový vstup, umožní úloze jej číst a udělí přístup k zápisu do samostatné výstupní složky. Oprávnění k síti a uživatelskému rozhraní zůstávají odepřena.

Hostitelská aplikace vytvoří politiku a zpracuje výsledek. Příkaz běží uvnitř MXC; zbytek hostitelské aplikace uvnitř MXC neběží.

Příklady používají rozhraní API sady SDK MXC 1.0 V1. Sady SDK V1 interně používají stabilní 1.0.0 schéma, takže v požadavku nezadávejte verzi schématu. Viz Zvolte kompatibilní schéma.

Prerequisites

Potřebujete:

• Windows 11, verze 24H2 nebo novější, s podporovaným prostředím ProcessContainer.
• Pro C# je potřeba sada .NET 8 SDK nebo novější a balíček NuGet Microsoft.Mxc.Sdk.
• Pro TypeScript, npm, balíček @microsoft/mxc-sdk a Node.js 24.21.0 nebo novější v řadě verzí Node.js 24 nebo Node.js 26.8.0 nebo novější.
• Pro Rust, stabilní rust toolchain s MSVC build tools a mxc-sdk crate. Viz Nastavte si vývojové prostředí Rustu ve Windows.
• Zapisovatelný pracovní adresář a PowerShell pro příkazy pro instalaci.

V pokynech se používají balíčky MXC 1.0 z NuGet.org, npm a crates.io. Není vyžadován žádný zdrojový build MXC.

Před spuštěním příkladu zkontrolujte podporu platformy . Podporovaná verze Windows nezaručuje dostupnost všech volitelných funkcí.

Na některých hostitelích MXC spouští izolaci procesů v alternativní vrstvě založené na AppContaineru. Tato vrstva potřebuje jednorázovou přípravu systémového disku a zařízení s hodnotou null a nastavení zařízení s hodnotou null se resetuje při každém restartování. Pokud chybí příprava, vrátí sonda hostitele MXC upozornění, které uvádí podpříkaz wxc-host-prep.exe, který se má spustit. Příklad TypeScriptu vytiskne tato upozornění z getPlatformSupport()a můžete také zkontrolovat hostitele spuštěním wxc-exec.exe --probe. Vzhledem k tomu, že wxc-host-prep.exe vyžaduje schválení správce, požádejte správce, aby spustil doporučený příkaz, namísto jeho spuštění z vaší aplikace. Podrobnosti najdete v tématu Příprava hostitele.

1. Vytvoření projektu

.NET

Vytvořte konzolovou aplikaci a přidejte balíček MXC z NuGet.org:

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

TypeScript

Vytvořte projekt Node.js, nainstalujte MXC a přidejte tsx pro spuštění příkladu TypeScriptu:

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

Rust

Vytvořte binární crate a přidejte crate MXC z crates.io:

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

2. Definujte a spusťte úlohu

Izolace procesů odpovídá tomuto krátkodobému příkazu, protože potřebuje vybrané soubory hostitele a žádné zachované prostředí. Jiné úlohy můžou vyžadovat jiný typ izolace.

Hostitel vytvoří workspace\input a workspace\output v adresáři projektu. Obsažený příkaz čte input.txt a zapisuje result.txt. Nemá přístup pro zápis do svého vstupního adresáře ani přístup k jiným souborům projektu.

Hostitel poskytuje malé explicitní prostředí namísto zdědění svých vlastních proměnných. Když zadáte prostředí pro Windows úlohy ProcessContainer, zahrňte obojí SystemRoot i LOCALAPPDATA. Pokud některý z nich chybí, MXC žádost před spuštěním odmítne. Ukázkové body LOCALAPPDATA, TEMP a TMP směřují na udělený výstupní adresář, aby dočasné a uživatelské soubory zůstaly v souladu se zásadami.

.NET

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

Spuštění aplikace:

dotnet run

TypeScript

Vytvořit pomocí sandbox.ts:

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

Spuštění aplikace:

npx tsx sandbox.ts

Rust

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

Spuštění aplikace:

cargo run

Každá verze tiskne:

Sandbox exited with code 0
Hello from MXC!

Můžete také zkontrolovat workspace\output\result.txt.

3. Ověřte odepřenou operaci

Změňte pouze deklaraci výstupního souboru, aby se příkaz pokusil zapisovat do vstupního adresáře jen pro čtení:

.NET

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

TypeScript

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

Rust

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

Spusťte aplikaci znovu beze změny zásady. Počítejte s chybou „Přístup odepřen“ a nenulovým ukončovacím kódem, aniž by se vytvořil nový soubor workspace\input\blocked.txt. Obnovte původní deklaraci výstupního souboru a ověřte, že povolená operace stále proběhne úspěšně.

Pokud povolené spuštění selže, odlište chyby nastavení hostitele nebo konfigurace od odepření přístupu ke zdroji. Použijte výukový režim k prozkoumání toho druhého; zásady automaticky nerozšiřujte.

4. Přizpůsobit příklad

Nahraďte ukázkový příkaz a vstupy důvěryhodnou reprezentativní zátěží. Zkontrolujte požadované binární soubory, knihovny, dočasné soubory a výstupy. Přidejte přístup k síti nebo uživatelskému rozhraní pouze v případech, kdy to úloha vyžaduje a vybraný back-end může vynutit zamýšlená omezení.

Otestujte povolené a odepřené operace na každém cílovém hostiteli. Když k upřesnění zásad použijete režim učení, zkontrolujte každé pozorování a dokončete vynucené spuštění bez nastavení učení nebo auditu.

Volitelné: použít agenta pro kódování

Dejte agentovi cílové platformy, jazyk a verzi sady SDK, příkaz, požadované prostředky, životní cyklus a cíle izolace. Tento prompt můžete přizpůsobit:

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.

Zkontrolujte předpoklady agenta a výslednou zásadu. Agent může pomoct s integrací, ale důvěryhodný kód hostitele nebo osoba musí schválit změny oprávnění úlohy.

Další kroky

• Než začnete používat trvalé nebo specializované back-endy, projděte si architekturu MXC a modely kontejnerizace.
• Naučte se vytvářet a ověřovat zásady MXC.
• Porovnejte možnosti izolace MXC a podporu platformy.
• Zkontrolujte celý pracovní postup Výukového režimu.
• Přizpůsobte příklady zásad MXC jiným úlohám.
• Vyhledejte balíčky SDK a poznámky k vydání v verzích MXC.