Attribute Reference

Every key each attribute accepts, as parsed by crates/pwrs-macros/src/params.rs, classes.rs, methods.rs, enums.rs and completers.rs (which also holds #[transform]), and the export_module! grammar in crates/pwrs/src/runtime.rs. An unknown key is a compile error naming it.

#[cmdlet(...)]

On a struct with named fields. Requires verb and noun. The struct must implement Default and Cmdlet.

The doc comment on the struct follows rustdoc’s own split: the first paragraph, every line up to the first blank one, is the synopsis, joined into a sentence; what follows is the description. Lines under a # Examples (or # Example) heading, one command per line, become help examples.

#[param(...)]

On a field of a #[cmdlet] struct. #[param] alone is valid. At most 64 parameters per cmdlet. The parameter name is the field name in PascalCase.

Field types are listed in Conversions Reference . Option<Option<T>> and Vec<Option<T>> are rejected.

raw is for bulk data. A parameter declared as an array type is the engine’s binder’s to check before the module is entered: on Windows PowerShell 5.1 it walks the array, 159 to 163 ms for a 4 MB byte[] and 1.3 s for 32 MB whether the array arrives bare or wrapped in a PSObject, against 0.9 ms and 5 ms for the same parameter marked raw; on pwsh 7.6.6 both cost the copy into the Vec<u8>, about 0.4 ms and 4.7 ms. An object[] of the values boxed, bound to a parameter declaring the array type, is converted one by one on both hosts, 717 ms and 2.2 s for 4 MB. docs/PERF.md carries the table. What raw costs is the binder’s own work: the parameter shows as object in Get-Help and completion, a wrong-typed argument is not refused at bind time, and a value the conversion cannot take is a PwrsConversionError from Rust instead. A string reaching a Vec<u8> this way enumerates as its characters rather than being rejected.

clr is the other way round: the binder does its work and Rust reads the result in place. A PsObject parameter is declared object, and an object parameter taking pipeline input accepts every piped record. Declared byte[] with clr, it accepts a byte array whole and a lone byte as an array of one, while a piped FileInfo, which does not convert, goes on to a literal_path parameter bound from its PSPath. The module then reads the bytes through pin, without a copy. Measure-RustInput in the hello example does both, and Bytes.Tests.ps1 checks each case in both hosts, including that the cmdlet can change the caller’s own array.

#[psclass(...)]

On a struct with named fields, at most 64. Fields need no attribute; each field’s doc comment becomes its property summary.

Generates PsClassMeta, IntoPs, PsTyped and FromPs. Field types are the parameter types, with bool becoming a bool property; a field may itself be a #[psclass] type, an Option or a Vec of one. Proxy mode reads fields through pwrs_proxy_get, so the struct’s fields are cloned on each read (Clone on the field types is required in that mode), and requires the type to be Send: the value is read, called and dropped on whatever thread holds the managed object (the finalizer thread for a value never disposed), and a non-Send type is a compile error at the attribute. Calls on one object never overlap, so Sync is not needed, and one that reaches the object again from inside a call on the same thread, such as a script reading a property while a cmdlet holds the object through PsProxy, is refused with a PwrsException rather than given a second reference to the value.

With PsTyped and FromPs the class is also a parameter type and a field type: the shell declares the class (PSObject for psobject mode), and FromPs reads the object back one field per property name, so a copied object, a proxy, or a PSObject carrying the notes all convert. A class used as a cmdlet parameter type needs Default, like every parameter type.

#[psfield(...)]

On a field of a #[psclass] struct.

A class with a skipped field keeps state no property shows, so it cannot be reconstructed by value: its FromPs returns a PwrsOpaqueClass error naming the fields, which is what a cmdlet parameter or method argument of that class reports when bound. Such a class still works as an output, a method return type, and a field type of another class, and a proxy one is taken as a parameter with PsProxy<T>, which reads the value in place; see How To Pass Native Data Between Cmdlets .

Reserved member names

A field or method whose PascalCase name would hide a member the generated class inherits is a compile error naming the set. Equals, GetHashCode, GetType and ToString come from System.Object and are reserved for the fields of a copied or proxy class and for every method; Dispose, IsDisposed, PwrsGet, PwrsCall and PwrsCallWith come from Pwrs.ProxyBase and are reserved as well for a proxy class’s fields and for every method. A psobject class generates no CLR type, so its fields are unrestricted.

Every other name is free, Get, Set, Call and Contains included: the generated property getters and method bodies reach the base class as base.PwrsGet(...) and base.PwrsCall(...), so a module method of any name is the one a script calls and never displaces the runtime’s own.

#[psenum(...)]

On a fieldless enum with at least one variant.

Discriminants: an explicit = n is used as given; otherwise the previous value plus one, starting at 0. Variant doc comments become member summaries. Generates PsTyped, PsClassMeta (mode enum), IntoPs and FromPs. The enum may then be a parameter type, a class field type, and an output.

name and clr are mutually exclusive, and giving both is a compile error. A clr enum mirrors a type the runtime already has: nothing is generated for it, it takes no class id, and it is not listed under enums: in export_module! (without PsClassMeta it cannot be, which is the guardrail rather than a second declaration of a type the shell does not own). What it buys is the parameter being declared as that CLR type, so the binder converts its member names, completes them, and rejects the rest before the body runs. A variant list narrower than the CLR enum’s members is allowed and useful: a member the Rust enum does not name binds and then fails in FromPs with PwrsEnumValue. IntoPs builds the value through the enum_new entry, which resolves the name the way a type literal does.

#[psmethods]

On impl Type { ... } where Type is a #[psclass] struct in proxy or copied mode. Takes no keys. Every pub fn in the block becomes a method of the generated class, named in PascalCase; private functions, constants, associated types and macro invocations are left alone. The impl block is emitted unchanged, so the methods stay callable from Rust. Self may be written anywhere a type is, PsResult<Self> and other: Self included, and names the class.

A method with a receiver, &self or &mut self, runs against the object, and so exists only on a proxy class. A pub fn with no receiver is a static method of the generated class, called on the type as [Ns.Type]::Name(...): it runs against no value, and a static that returns the class returns a new object of it. The static named new that returns PsResult<Self> is the class’s constructor, reached as [Ns.Type]::new(...), and a new returning anything else is a compile error. Rust has no overloading, so a class has one new; Option<T> arguments make it callable with fewer arguments, and one new(a: Option<i64>, b: Option<i64>) answers [T]::new(), [T]::new(1) and [T]::new(1, 2).

A method may take one argument PsTask<T> and then returns PsResult<()>: the generated method returns Task<T> (Task for PsTask<()>, T declared as an argument of T would be, so PsTask<Option<i64>> returns Task<long?> and complete(None) completes it with $null), takes no parameter for the PsTask itself, and gains a last parameter CancellationToken cancellationToken = default. The method moves the PsTask to the thread that does the work, which settles it with complete, fail or cancel; the token sets a flag that is_cancelled reads, and the task ends canceled when the module calls cancel, so a cancellation never discards a result the work has already taken. A task dropped unsettled faults with PwrsTaskDropped. An Err from the method itself is thrown by the call, as for any method. Another argument named cancellation_token is refused by cargo pwrs build, and a constructor takes no PsTask.

A method with a receiver may take one argument &Self (or &Type): another object of the class, lent shared for the call. The generated method declares the class as the parameter type, throws ArgumentNullException for $null, and enters both objects’ gates before the call, the receiver as the method takes it and the other as shared, always in the order the two objects were made, so two threads calling across the same pair the opposite way round never wait on each other. The same object as both is entered once, and refused to a &mut self method. A static takes no &Self, nor a method two; any other reference type is a compile error.

A constructor has no pipeline, so it cannot write a warning or an error record: an Err is the exception the script’s ::new call throws. A condition a cmdlet would warn about is either refused in a constructor or left silent there, and a cmdlet that must warn keeps its own check.

On a proxy class the value new returns is the one the new object holds.

On a copied class there is no Rust value behind the object, so only statics can be declared, and a method taking &self is refused by cargo pwrs build with the reason. new builds the value in Rust and the new object is made from it field by field, so its properties are ordinary settable fields like any other copied object’s. What a script can construct depends on whether the class declares a new:

To keep a parameterless constructor that starts from the type’s Default rather than zeros, give new all-Option arguments and start from Self::default(). The generated factory builds objects through a constructor of its own, selected by the runtime’s Pwrs.FromFields marker, which no Rust signature lowers to; so it never calls a constructor the module declared, and a new() that returns Self cannot call itself through the factory. Arguments are of the parameter types (Option<T> makes the C# parameter optional with a null default; bool is a bool, not a switch; a #[psclass] type is read back through its properties), and returns PsResult<T> for any of those types, including a #[psclass] type (a proxy class returned this way is a new proxy object), or PsResult<()> for nothing. An Option<String> or Option<PathBuf> argument is declared as object? rather than string?: the engine’s method binder turns $null and an omitted argument into an empty string for a string parameter, so None would never arrive; the generated method converts a supplied value to a string itself. Async and generic methods are rejected; at most 64 arguments. The method’s doc comment becomes its <summary>.

Generates a PsMethods<Type> impl on MethodsCollector<Type> carrying the method descriptors and the dispatch; #[psclass] finds it through method resolution, so a class without #[psmethods] needs nothing. cargo pwrs build refuses methods on a psobject or enum class, and a method taking &self on a copied one. Each call is one pwrs_proxy_call with a packed argument block; calls and property reads on one proxy are serialized by the managed base; an Err from the method becomes a PwrsException in the script. A static or a constructor is the same call with a null instance, through the runtime’s Pwrs.StaticCall.Invoke, which serializes nothing and checks no generation because there is no object to guard. A method with a receiver reached with a null instance is refused with PwrsNoInstance rather than run. The constructor’s call answers, for a proxy, the new value’s pointer, which the public constructor hands to the internal one; for a copied class, the object the class’s factory built, whose fields the public constructor copies into itself.

#[completer(...)]

On a fn(ctx: &CompletionContext) -> PsResult<Vec<Completion>>. Both keys required.

The function becomes a unit struct of the same name implementing CompleterFn; list that name under completers.

#[transform(...)]

On a fn(value: &PsObject) -> PsResult<PsObject>. Both keys required, and one transform per parameter.

The function becomes a unit struct of the same name implementing TransformFn; list that name under transforms. It generates an ArgumentTransformationAttribute on the parameter, which the engine runs before coercing the argument to the parameter’s declared type and before validation, so a long parameter can accept 2MB and a refusal is a binding failure naming the parameter rather than an error the cmdlet wrote.

The value arrives as the caller wrote it, so a transform reads it defensively and hands back anything it does not recognize for the binder to coerce or reject; returning the value unchanged is always correct. No instance exists yet, so it takes no Pipeline and cannot write to a stream.

#[dynamic_params(...)]

On a fn(bound: &PsHashtable) -> PsResult<Vec<DynamicParam>>.

Implements DynamicParams for that type; list the cmdlet type under dynamic_params.

#[on_import] and #[on_remove]

Each on a fn() -> PsResult<()>. Neither takes a key; a key or an argument to the function is a compile error.

The function becomes a unit struct of the same name implementing OnImport or OnRemove; name it under on_import or on_remove. The generated shell implements IModuleAssemblyInitializer for a declared on_import and IModuleAssemblyCleanup for a declared on_remove, and neither interface otherwise, so a module without hooks is not called at import or removal. A hook runs on the thread executing Import-Module or Remove-Module, with no cmdlet and no pipeline.

A removal unloads nothing: the native library stays mapped and its statics keep their values. So on_import runs on every import, including one that follows a removal in the same session, and on_remove is the only place an import’s resources are released. An Err from on_import fails the import; an Err from on_remove is reported by Remove-Module and the removal goes ahead. On a reload the old library’s on_remove runs before the new library’s on_import; see How To Reload A Module .

#[provider(...)]

On a struct implementing Provider; one value of it serves one drive.

The struct’s doc comment is the provider description in the descriptor.

export_module!

pwrs::export_module! {
    name: "Hello",
    cmdlets: [GetGreeting, GetPerson],
    classes: [Person, Counter],
    enums: [Signal],
    completers: [complete_color],
    transforms: [as_bytes],
    dynamic_params: [GetRustReading],
    providers: [MemFs],
    on_import: count_import,
    on_remove: count_remove,
}

name and cmdlets are required (cmdlets: [] is allowed); the other entries are optional and must appear in this order when present. on_import and on_remove each name one unit struct, not a list. The position of each list entry is its id: cmdlets from 0; classes then enums share one id space in that order; completers, transforms and providers each from 0. The macro emits the pwrs_module_init, pwrs_module_descriptor, pwrs_cmdlet_*, pwrs_proxy_*, pwrs_completer_invoke, pwrs_transform_invoke, pwrs_dynparams_invoke, pwrs_provider_invoke and pwrs_module_lifecycle exports. One export_module! per crate.