Краткое руководство. Запуск рабочей нагрузки с помощью пакета SDK MXC

Используйте пакет SDK .NET, TypeScript или Rust, чтобы выполнить команду в режиме изоляции процессов Windows. Каждый пример создает образец входных данных, позволяет рабочей нагрузке читать их и предоставляет рабочей нагрузке доступ на запись в отдельную выходную папку. Разрешения сети и пользовательского интерфейса по-прежнему не предоставлены.

Главное приложение создает политику и обрабатывает результат. Команда выполняется внутри MXC; остальная часть хост-приложения не выполняется.

В примерах используются API SDK MXC 1.0 V1. Пакеты SDK версии 1 используют стабильную схему 1.0.0 внутри системы, поэтому в запросе не нужно указывать версию схемы. См. раздел Выбор совместимой схемы.

Prerequisites

Тебе нужно:

• Windows 11 версии 24H2 или более поздней, в поддерживаемой среде ProcessContainer.
• Для C# требуются .NET 8 SDK или более поздней версии и пакет NuGet Microsoft.Mxc.Sdk.
• Требуются TypeScript, npm, пакет @microsoft/mxc-sdk и Node.js 24.21.0 или более поздней версии в ветке выпуска Node.js 24 либо Node.js 26.8.0 или более поздней версии.
• Для Rust — стабильная цепочка инструментов Rust с инструментами сборки MSVC и crate mxc-sdk. См. статью "Настройка среды разработки Rust" в Windows.
• Рабочий каталог с возможностью записи и PowerShell для команд установки.

В инструкциях используются пакеты MXC 1.0 из NuGet.org, npm и crates.io. Сборка из исходников MXC не требуется.

Перед запуском примера проверьте поддержку платформы . Поддерживаемая версия Windows не гарантирует доступность каждой необязательной функции.

На некоторых узлах MXC выполняет изоляцию процесса в резервном уровне на основе AppContainer. Для этого уровня требуется однократная подготовка системного диска и устройства NULL, а параметры null-устройства сбрасываются при каждом перезапуске. При отсутствии подготовки проба узла MXC возвращает предупреждение с указанием подкоманды wxc-host-prep.exe, которую нужно выполнить. В примере TypeScript выводятся эти предупреждения из getPlatformSupport(), а также можно проверить хост, выполнив команду wxc-exec.exe --probe. Так как для wxc-host-prep.exe требуется одобрение администратора, попросите администратора выполнить рекомендуемую команду, а не запускать ее из приложения. Дополнительные сведения см. в разделе Подготовка узла.

1. Создание проекта

.NET

Создайте консольное приложение и добавьте пакет MXC из NuGet.org:

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

TypeScript

Создайте проект Node.js, установите MXC и добавьте tsx для запуска примера 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

Rust

Создайте бинарный crate и добавьте crate MXC из crates.io:

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

2. Определите и запустите рабочую нагрузку

Изоляция процессов соответствует этой кратковременной команде, так как ей нужны выбранные файлы хоста и без сохранения окружения. Для других рабочих нагрузок может потребоваться другой тип контейнера.

Хост создает workspace\input и workspace\output под каталогом проекта. Содержащаяся команда считывает result.txtи записываетinput.txt. Он не получает доступ на запись к входной папке или доступ к другим файлам проекта.

Хост предоставляет небольшую явную среду вместо того, чтобы наследовать свои переменные среды. Если вы предоставляете среду для рабочей нагрузки Windows ProcessContainer, включите оба SystemRoot иLOCALAPPDATA. MXC отклоняет запрос перед запуском, если любой из двух отсутствует. Пример указывает точки LOCALAPPDATA, TEMP и TMP на предоставленный выходной каталог, чтобы временные и пользовательские файлы оставались в рамках политики.

.NET

Замените 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;
}

Запустите приложение:

dotnet run

TypeScript

Создайте 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;
}

Запустите приложение:

npx tsx sandbox.ts

Rust

Замените 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)
}

Запустите приложение:

cargo run

Каждая версия печатает:

Sandbox exited with code 0
Hello from MXC!

Вы также можете проверить workspace\output\result.txt.

3. Проверьте запрещенную операцию

Измените только объявление выходного файла, чтобы команда попыталась записать в каталог входных данных только для чтения:

.NET

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

TypeScript

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

Rust

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

Снова запустите приложение, не изменяя политику. Ожидается ошибка «Отказано в доступе» и ненулевой код выхода без нового файла workspace\input\blocked.txt. Восстановите исходное объявление выходного файла и убедитесь, что разрешенная операция по-прежнему выполняется успешно.

Если разрешенный запуск завершается сбоем, различайте ошибки настройки хоста или конфигурации и отказ в ресурсе. Используйте режим обучения, чтобы изучить последнее; не расширяйте политику автоматически.

4. Адаптируйте пример

Замените пример команды и входные данные на надежную репрезентативную рабочую нагрузку. Просмотрите двоичные файлы, библиотеки, временные файлы и выходные данные необходимого инструмента. Добавьте доступ к сети или пользовательскому интерфейсу только в том случае, если этого требует задача, а выбранный бэкенд может применить предполагаемые ограничения.

Тестирование разрешенных и запрещенных операций на каждом целевом узле. При использовании режима обучения для уточнения политики просмотрите каждое наблюдение и завершите принудительным запуском без параметров обучения или аудита.

Необязательно: используйте агента для программирования

Предоставьте агенту целевые платформы, язык пакета SDK и версию, команду, необходимые ресурсы, жизненный цикл и цели изоляции. Вы можете адаптировать этот запрос:

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.

Ознакомьтесь с предположениями агента и полученным правилом. Агент может помочь в интеграции, но доверенный код узла или человек должен утвердить изменения в полномочиях рабочей нагрузки.

Дальнейшие действия

• Ознакомьтесь с архитектурой MXC и моделями изоляции перед использованием постоянных или специализированных бэкендов.
• Узнайте, как создавать и проверять политику MXC.
• Сравните варианты изоляции MXC и поддержку платформы.
• Просмотрите полный рабочий процесс режима обучения.
• Адаптируйте примеры политики MXC к другим рабочим нагрузкам.
• Найдите пакеты SDK и заметки о выпуске в выпусках MXC.