Crate vim_rs 

VMware vSphere API Client for Rust

Async client for the VMware vSphere Virtual Infrastructure API. The default transport is VI/JSON. SOAP/XML is optional (xml feature) for direct ESXi connectivity.

This page is the API reference. The user guide — connecting, TLS, property retrieval, tasks, and the XML transport — is the crate README. Design notes are in vim_rs/docs.

Connecting to vCenter

use vim_rs::core::ClientBuilder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = ClientBuilder::new("vcenter.example.com")
        .basic_authn("administrator@vsphere.local", "password")
        .app_details(env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"))
        .insecure(true) // self-signed certificates
        .build()
        .await?;

    client.close().await?;
    Ok(())
}

build returns Arc<Client> with a session and service content loaded. Clone the Arc to share it. .app_details names the session in the vCenter UI and SessionManager. .insecure(true) skips hostname and certificate checks.

The default-client feature (on by default) builds a reqwest client that uses rustls. To supply your own TLS stack, set default-features = false and call ClientBuilder::new(server, http_client).

Call Client::close at shutdown. If close was never called, dropping the last inner handle still logs out on a multi-thread Tokio runtime and warns on current_thread.

Managed objects

A stub needs the session, the managed-object type, and an id. Root objects are on service content. PropertyCollector is always present.

let content = client.service_content();
let property_collector = PropertyCollector::new(client.clone(), &content.property_collector.value);

Properties and methods are both remote calls:

let events = collector.read_next_events(10).await?;
let vms = view.view().await?;

Property retrieval

vim_retrievable! maps property paths onto a struct and loads them in one PropertyCollector call. vim_updatable! keeps a local replica. Both are exported from this crate. Full samples are in the crate README.

use vim_rs::vim_retrievable;
use vim_rs::core::pc_retrieve::ObjectRetriever;

vim_retrievable!(
    struct Host: HostSystem {
        name = "name",
        power_state = "runtime.power_state",
    }
);

let retriever = ObjectRetriever::new(client.clone())?;
let hosts: Vec<Host> = retriever
    .retrieve_objects_from_container(&client.service_content().root_folder)
    .await?;

Features

Feature	Default	Effect
default-client	on	reqwest client with rustls.
xml	off	Experimental SOAP/XML. About +500 KB release binary size and +30–40% debug build time. Core VIM only.
defaults	off	Default for generated types. Large extra generated source and compile time.
vcsim_compat	off	Tolerant SOAP parsing for govc vcsim. Requires xml.
perf	off	vim_rs::perf: named performance queries and the generated counter catalog.
perf-chrono	off	Timestamp ↔ chrono::DateTime<Utc>. Enables perf.
perf-polars	off	PerfResult::to_dataframe. Enables perf. Polars 0.55 is outside the vim_rs semver.

XML does not negotiate the API release via Hello. Use client.service_content().about.api_version when server capabilities matter.

Type system

Deep VIM inheritance uses traits and compositional inheritance: a child struct holds its parent and Derefs to it. Wide sums (VimAny, ValueElements) are enums. MethodFault and Event subtypes are pruned; subtype fields live in extra_fields_. See the type system notes.

Re-exports

pub use core::WireLoggingMode;

Modules

core

mo

types

Macros

vim_retrievable

A macro to generate a struct and implementation necessary to work with PropertyCollector::RetrievePropertiesEx API. Developers need to select the managed object type of interest and the properties they need retrieved. For example to retrieve properties of a VirtualMachine object, the macro can be used as follows:

vim_updatable

A macro to generate a struct and implementation necessary to work with PropertyCollector::wait_for_updates_ex API. Developers need to select the managed object type of interest and the properties they need replicated. For example to replicate properties of a VirtualMachine object, the macro can be used as follows: