diff --git a/src/Components/dotnet-runtime-js/dotnet.d.ts b/src/Components/dotnet-runtime-js/dotnet.d.ts index 1fc6e2952fe2..07428895e9d4 100644 --- a/src/Components/dotnet-runtime-js/dotnet.d.ts +++ b/src/Components/dotnet-runtime-js/dotnet.d.ts @@ -1,7 +1,7 @@ //! Licensed to the .NET Foundation under one or more agreements. //! The .NET Foundation licenses this file to you under the MIT license. //! -//! This is generated file, see src/mono/wasm/runtime/rollup.config.js +//! This is generated file, see src/mono/browser/runtime/rollup.config.js //! This is not considered public API with backward compatibility guarantees. @@ -18,26 +18,9 @@ declare interface Int32Ptr extends NativePointer { __brand: "Int32Ptr"; } declare interface EmscriptenModule { - /** @deprecated Please use growableHeapI8() instead.*/ - HEAP8: Int8Array; - /** @deprecated Please use growableHeapI16() instead.*/ - HEAP16: Int16Array; - /** @deprecated Please use growableHeapI32() instead. */ - HEAP32: Int32Array; - /** @deprecated Please use growableHeapI64() instead. */ - HEAP64: BigInt64Array; - /** @deprecated Please use growableHeapU8() instead. */ - HEAPU8: Uint8Array; - /** @deprecated Please use growableHeapU16() instead. */ - HEAPU16: Uint16Array; - /** @deprecated Please use growableHeapU32() instead */ - HEAPU32: Uint32Array; - /** @deprecated Please use growableHeapF32() instead */ - HEAPF32: Float32Array; - /** @deprecated Please use growableHeapF64() instead. */ - HEAPF64: Float64Array; _malloc(size: number): VoidPtr; _free(ptr: VoidPtr): void; + _sbrk(size: number): VoidPtr; out(message: string): void; err(message: string): void; ccall(ident: string, returnType?: string | null, argTypes?: string[], args?: any[], opts?: any): T; @@ -49,6 +32,7 @@ declare interface EmscriptenModule { UTF8ToString(ptr: CharPtr, maxBytesToRead?: number): string; UTF8ArrayToString(u8Array: Uint8Array, idx?: number, maxBytesToRead?: number): string; stringToUTF8Array(str: string, heap: Uint8Array, outIdx: number, maxBytesToWrite: number): void; + lengthBytesUTF8(str: string): number; FS_createPath(parent: string, path: string, canRead?: boolean, canWrite?: boolean): string; FS_createDataFile(parent: string, name: string, data: TypedArray, canRead: boolean, canWrite: boolean, canOwn?: boolean): string; addFunction(fn: Function, signature: string): number; @@ -72,26 +56,83 @@ type InstantiateWasmCallBack = (imports: WebAssembly.Imports, successCallback: I declare type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array; interface DotnetHostBuilder { + /** + * @param config default values for the runtime configuration. It will be merged with the default values. + * Note that if you provide resources and don't provide custom configSrc URL, the dotnet.boot.js will be downloaded and applied by default. + */ withConfig(config: MonoConfig): DotnetHostBuilder; + /** + * @param configSrc URL to the configuration file. ./dotnet.boot.js is a default config file location. + */ withConfigSrc(configSrc: string): DotnetHostBuilder; + /** + * "command line" arguments for the Main() method. + * @param args + */ withApplicationArguments(...args: string[]): DotnetHostBuilder; + /** + * Sets the environment variable for the "process" + */ withEnvironmentVariable(name: string, value: string): DotnetHostBuilder; + /** + * Sets the environment variables for the "process" + */ withEnvironmentVariables(variables: { [i: string]: string; }): DotnetHostBuilder; + /** + * Sets the "current directory" for the "process" on the virtual file system. + */ withVirtualWorkingDirectory(vfsPath: string): DotnetHostBuilder; + /** + * @param enabled if "true", writes diagnostic messages during runtime startup and execution to the browser console. + */ withDiagnosticTracing(enabled: boolean): DotnetHostBuilder; + /** + * @param level + * level > 0 enables debugging and sets the logging level to debug + * level == 0 disables debugging and enables interpreter optimizations + * level < 0 enables debugging and disables debug logging. + */ withDebugging(level: number): DotnetHostBuilder; + /** + * @param mainAssemblyName Sets the name of the assembly with the Main() method. Default is the same as the .csproj name. + */ withMainAssembly(mainAssemblyName: string): DotnetHostBuilder; + /** + * Supply "command line" arguments for the Main() method from browser query arguments named "arg". Eg. `index.html?arg=A&arg=B&arg=C`. + * @param args + */ withApplicationArgumentsFromQuery(): DotnetHostBuilder; + /** + * Sets application environment, such as "Development", "Staging", "Production", etc. + */ withApplicationEnvironment(applicationEnvironment?: string): DotnetHostBuilder; + /** + * Sets application culture. This is a name specified in the BCP 47 format. See https://tools.ietf.org/html/bcp47 + */ withApplicationCulture(applicationCulture?: string): DotnetHostBuilder; /** * Overrides the built-in boot resource loading mechanism so that boot resources can be fetched * from a custom source, such as an external CDN. */ withResourceLoader(loadBootResource?: LoadBootResourceCallback): DotnetHostBuilder; + /** + * Downloads all the assets but doesn't create the runtime instance. + */ + download(): Promise; + /** + * Starts the runtime and returns promise of the API object. + */ create(): Promise; + /** + * Runs the Main() method of the application and exits the runtime. + * You can provide "command line" arguments for the Main() method using + * - dotnet.withApplicationArguments(["A", "B", "C"]) + * - dotnet.withApplicationArgumentsFromQuery() + * Note: after the runtime exits, it would reject all further calls to the API. + * You can use runMain() if you want to keep the runtime alive. + */ run(): Promise; } type MonoConfig = { @@ -129,6 +170,18 @@ type MonoConfig = { * Gets a value that determines whether to enable caching of the 'resources' inside a CacheStorage instance within the browser. */ cacheBootResources?: boolean; + /** + * Delay of the purge of the cached resources in milliseconds. Default is 10000 (10 seconds). + */ + cachedResourcesPurgeDelay?: number; + /** + * Configures use of the `integrity` directive for fetching assets + */ + disableIntegrityCheck?: boolean; + /** + * Configures use of the `no-cache` directive for fetching assets + */ + disableNoCacheFetch?: boolean; /** * Enables diagnostic log messages during startup */ @@ -139,14 +192,34 @@ type MonoConfig = { environmentVariables?: { [i: string]: string; }; + /** + * Subset of runtimeconfig.json + */ + runtimeConfig?: { + runtimeOptions?: { + configProperties?: { + [i: string]: string | number | boolean; + }; + }; + }; /** * initial number of workers to add to the emscripten pthread pool */ - pthreadPoolSize?: number; + pthreadPoolInitialSize?: number; /** - * If true, the snapshot of runtime's memory will be stored in the browser and used for faster startup next time. Default is false. + * number of unused workers kept in the emscripten pthread pool after startup */ - startupMemoryCache?: boolean; + pthreadPoolUnusedSize?: number; + /** + * If true, a list of the methods optimized by the interpreter will be saved and used for faster startup + * on future runs of the application + */ + interpreterPgo?: boolean; + /** + * Configures how long to wait before saving the interpreter PGO list. If your application takes + * a while to start you should adjust this value. + */ + interpreterPgoSaveDelay?: number; /** * application environment */ @@ -169,17 +242,31 @@ type MonoConfig = { extensions?: { [name: string]: any; }; + /** + * This is initial working directory for the runtime on the virtual file system. Default is "/". + */ + virtualWorkingDirectory?: string; + /** + * This is the arguments to the Main() method of the program when called with dotnet.run() Default is []. + * Note: RuntimeAPI.runMain() and RuntimeAPI.runMainAndExit() will replace this value, if they provide it. + */ + applicationArguments?: string[]; }; type ResourceExtensions = { [extensionName: string]: ResourceList; }; interface ResourceGroups { hash?: string; + fingerprinting?: { + [name: string]: string; + }; + coreAssembly?: ResourceList; assembly?: ResourceList; lazyAssembly?: ResourceList; + corePdb?: ResourceList; pdb?: ResourceList; jsModuleWorker?: ResourceList; - jsModuleGlobalization?: ResourceList; + jsModuleDiagnostics?: ResourceList; jsModuleNative: ResourceList; jsModuleRuntime: ResourceList; wasmSymbols?: ResourceList; @@ -191,6 +278,9 @@ interface ResourceGroups { modulesAfterConfigLoaded?: ResourceList; modulesAfterRuntimeReady?: ResourceList; extensions?: ResourceExtensions; + coreVfs?: { + [virtualPath: string]: ResourceList; + }; vfs?: { [virtualPath: string]: ResourceList; }; @@ -208,22 +298,36 @@ type ResourceList = { * @param name The name of the resource to be loaded. * @param defaultUri The URI from which the framework would fetch the resource by default. The URI may be relative or absolute. * @param integrity The integrity string representing the expected content in the response. + * @param behavior The detailed behavior/type of the resource to be loaded. * @returns A URI string or a Response promise to override the loading process, or null/undefined to allow the default loading behavior. * When returned string is not qualified with `./` or absolute URL, it will be resolved against the application base URI. */ -type LoadBootResourceCallback = (type: WebAssemblyBootResourceType, name: string, defaultUri: string, integrity: string, behavior: AssetBehaviors) => string | Promise | null | undefined; -interface ResourceRequest { - name: string; - behavior: AssetBehaviors; - resolvedUrl?: string; - hash?: string | null | ""; -} +type LoadBootResourceCallback = (type: WebAssemblyBootResourceType, name: string, defaultUri: string, integrity: string, behavior: AssetBehaviors) => string | Promise | Promise | null | undefined; +type BootModule = { + config: MonoConfig; +}; interface LoadingResource { name: string; url: string; response: Promise; } -interface AssetEntry extends ResourceRequest { +interface AssetEntry { + /** + * the name of the asset, including extension. + */ + name: string; + /** + * determines how the asset will be handled once loaded + */ + behavior: AssetBehaviors; + /** + * this should be absolute url to the asset + */ + resolvedUrl?: string; + /** + * the integrity hash of the asset (if any) + */ + hash?: string | null | ""; /** * If specified, overrides the path of the asset in the virtual filesystem and similar data structures once downloaded. */ @@ -244,7 +348,12 @@ interface AssetEntry extends ResourceRequest { * If provided, runtime doesn't have to fetch the data. * Runtime would set the buffer to null after instantiation to free the memory. */ - buffer?: ArrayBuffer; + buffer?: ArrayBuffer | Promise; + /** + * If provided, runtime doesn't have to import it's JavaScript modules. + * This will not work for multi-threaded runtime. + */ + moduleExports?: any | Promise; /** * It's metadata + fetch-like Promise * If provided, the runtime doesn't have to initiate the download. It would just await the response. @@ -253,7 +362,7 @@ interface AssetEntry extends ResourceRequest { } type SingleAssetBehaviors = /** - * The binary of the dotnet runtime. + * The binary of the .NET runtime. */ "dotnetwasm" /** @@ -264,6 +373,10 @@ type SingleAssetBehaviors = * The javascript module for threads. */ | "js-module-threads" +/** + * The javascript module for diagnostic server and client. + */ + | "js-module-diagnostics" /** * The javascript module for runtime. */ @@ -273,13 +386,13 @@ type SingleAssetBehaviors = */ | "js-module-native" /** - * The javascript module for hybrid globalization. + * Typically dotnet.boot.js */ - | "js-module-globalization" + | "manifest" /** - * Typically blazor.boot.json + * The debugging symbols */ - | "manifest"; + | "symbols"; type AssetBehaviors = SingleAssetBehaviors | /** * Load asset as a managed resource assembly. @@ -308,11 +421,7 @@ type AssetBehaviors = SingleAssetBehaviors | /** * The javascript module that came from nuget package . */ - | "js-module-library-initializer" -/** - * The javascript module for threads. - */ - | "symbols"; + | "js-module-library-initializer"; declare const enum GlobalizationMode { /** * Load sharded ICU data. @@ -329,14 +438,9 @@ declare const enum GlobalizationMode { /** * Use user defined icu file. */ - Custom = "custom", - /** - * Operate in hybrid globalization mode with small ICU files, using native platform functions. - */ - Hybrid = "hybrid" + Custom = "custom" } type DotnetModuleConfig = { - disableDotnet6Compatibility?: boolean; config?: MonoConfig; configSrc?: string; onConfigLoaded?: (config: MonoConfig) => void | Promise; @@ -345,57 +449,237 @@ type DotnetModuleConfig = { imports?: any; exports?: string[]; } & Partial; -type APIType = { - runMain: (mainAssemblyName: string, args: string[]) => Promise; - runMainAndExit: (mainAssemblyName: string, args: string[]) => Promise; +type RunAPIType = { + /** + * Runs the Main() method of the application. + * Note: this will keep the .NET runtime alive and the APIs will be available for further calls. + * @param mainAssemblyName name of the assembly with the Main() method. Optional. Default is the same as the .csproj name. + * @param args command line arguments for the Main() method. Optional. + * @returns exit code of the Main() method. + */ + runMain: (mainAssemblyName?: string, args?: string[]) => Promise; + /** + * Runs the Main() method of the application and exits the runtime. + * Note: after the runtime exits, it would reject all further calls to the API. + * @param mainAssemblyName name of the assembly with the Main() method. Optional. Default is the same as the .csproj name. + * @param args command line arguments for the Main() method. Optional. + * @returns exit code of the Main() method. + */ + runMainAndExit: (mainAssemblyName?: string, args?: string[]) => Promise; + /** + * Exits the runtime. + * Note: after the runtime exits, it would reject all further calls to the API. + * @param code "process" exit code. + * @param reason could be a string or an Error object. + */ + exit: (code: number, reason?: any) => void; + /** + * Sets the environment variable for the "process" + * @param name + * @param value + */ setEnvironmentVariable: (name: string, value: string) => void; + /** + * Returns the [JSExport] methods of the assembly with the given name + * @param assemblyName + */ getAssemblyExports(assemblyName: string): Promise; + /** + * Provides functions which could be imported by the managed code using [JSImport] + * @param moduleName maps to the second parameter of [JSImport] + * @param moduleImports object with functions which could be imported by the managed code. The keys map to the first parameter of [JSImport] + */ setModuleImports(moduleName: string, moduleImports: any): void; + /** + * Returns the configuration object used to start the runtime. + */ getConfig: () => MonoConfig; + /** + * Executes scripts which were loaded during runtime bootstrap. + * You can register the scripts using MonoConfig.resources.modulesAfterConfigLoaded and MonoConfig.resources.modulesAfterRuntimeReady. + */ invokeLibraryInitializers: (functionName: string, args: any[]) => Promise; +}; +type MemoryAPIType = { + /** + * Writes to the WASM linear memory + */ setHeapB32: (offset: NativePointer, value: number | boolean) => void; + /** + * Writes to the WASM linear memory + */ + setHeapB8: (offset: NativePointer, value: number | boolean) => void; + /** + * Writes to the WASM linear memory + */ setHeapU8: (offset: NativePointer, value: number) => void; + /** + * Writes to the WASM linear memory + */ setHeapU16: (offset: NativePointer, value: number) => void; + /** + * Writes to the WASM linear memory + */ setHeapU32: (offset: NativePointer, value: NativePointer | number) => void; + /** + * Writes to the WASM linear memory + */ setHeapI8: (offset: NativePointer, value: number) => void; + /** + * Writes to the WASM linear memory + */ setHeapI16: (offset: NativePointer, value: number) => void; + /** + * Writes to the WASM linear memory + */ setHeapI32: (offset: NativePointer, value: number) => void; + /** + * Writes to the WASM linear memory + */ setHeapI52: (offset: NativePointer, value: number) => void; + /** + * Writes to the WASM linear memory + */ setHeapU52: (offset: NativePointer, value: number) => void; + /** + * Writes to the WASM linear memory + */ setHeapI64Big: (offset: NativePointer, value: bigint) => void; + /** + * Writes to the WASM linear memory + */ setHeapF32: (offset: NativePointer, value: number) => void; + /** + * Writes to the WASM linear memory + */ setHeapF64: (offset: NativePointer, value: number) => void; + /** + * Reads from the WASM linear memory + */ getHeapB32: (offset: NativePointer) => boolean; + /** + * Reads from the WASM linear memory + */ + getHeapB8: (offset: NativePointer) => boolean; + /** + * Reads from the WASM linear memory + */ getHeapU8: (offset: NativePointer) => number; + /** + * Reads from the WASM linear memory + */ getHeapU16: (offset: NativePointer) => number; + /** + * Reads from the WASM linear memory + */ getHeapU32: (offset: NativePointer) => number; + /** + * Reads from the WASM linear memory + */ getHeapI8: (offset: NativePointer) => number; + /** + * Reads from the WASM linear memory + */ getHeapI16: (offset: NativePointer) => number; + /** + * Reads from the WASM linear memory + */ getHeapI32: (offset: NativePointer) => number; + /** + * Reads from the WASM linear memory + */ getHeapI52: (offset: NativePointer) => number; + /** + * Reads from the WASM linear memory + */ getHeapU52: (offset: NativePointer) => number; + /** + * Reads from the WASM linear memory + */ getHeapI64Big: (offset: NativePointer) => bigint; + /** + * Reads from the WASM linear memory + */ getHeapF32: (offset: NativePointer) => number; + /** + * Reads from the WASM linear memory + */ getHeapF64: (offset: NativePointer) => number; + /** + * Returns a short term view of the WASM linear memory. Don't store the reference, don't use it after await. + */ localHeapViewI8: () => Int8Array; + /** + * Returns a short term view of the WASM linear memory. Don't store the reference, don't use it after await. + */ localHeapViewI16: () => Int16Array; + /** + * Returns a short term view of the WASM linear memory. Don't store the reference, don't use it after await. + */ localHeapViewI32: () => Int32Array; + /** + * Returns a short term view of the WASM linear memory. Don't store the reference, don't use it after await. + */ localHeapViewI64Big: () => BigInt64Array; + /** + * Returns a short term view of the WASM linear memory. Don't store the reference, don't use it after await. + */ localHeapViewU8: () => Uint8Array; + /** + * Returns a short term view of the WASM linear memory. Don't store the reference, don't use it after await. + */ localHeapViewU16: () => Uint16Array; + /** + * Returns a short term view of the WASM linear memory. Don't store the reference, don't use it after await. + */ localHeapViewU32: () => Uint32Array; + /** + * Returns a short term view of the WASM linear memory. Don't store the reference, don't use it after await. + */ localHeapViewF32: () => Float32Array; + /** + * Returns a short term view of the WASM linear memory. Don't store the reference, don't use it after await. + */ localHeapViewF64: () => Float64Array; }; -type RuntimeAPI = { +type DiagnosticsAPIType = { + /** + * creates diagnostic trace file. Default is 60 seconds. + * It could be opened in PerfView or Visual Studio as is. + */ + collectCpuSamples: (options?: DiagnosticCommandOptions) => Promise; + /** + * creates diagnostic trace file. Default is 60 seconds. + * It could be opened in PerfView or Visual Studio as is. + * It could be summarized by `dotnet-trace report xxx.nettrace topN -n 10` + */ + collectPerfCounters: (options?: DiagnosticCommandOptions) => Promise; /** - * @deprecated Please use API object instead. See also MONOType in dotnet-legacy.d.ts + * creates diagnostic trace file. + * It could be opened in PerfView as is. + * It could be converted for Visual Studio using `dotnet-gcdump convert`. */ - MONO: any; + collectGcDump: (options?: DiagnosticCommandOptions) => Promise; /** - * @deprecated Please use API object instead. See also BINDINGType in dotnet-legacy.d.ts + * changes DOTNET_DiagnosticPorts and makes a new connection to WebSocket on that URL. */ - BINDING: any; + connectDSRouter(url: string): void; +}; +type DiagnosticCommandProviderV2 = { + keywords: [number, number]; + logLevel: number; + provider_name: string; + arguments: string | null; +}; +type DiagnosticCommandOptions = { + durationSeconds?: number; + intervalSeconds?: number; + skipDownload?: boolean; + circularBufferMB?: number; + extraProviders?: DiagnosticCommandProviderV2[]; +}; +type APIType = RunAPIType & MemoryAPIType & DiagnosticsAPIType; +type RuntimeAPI = { INTERNAL: any; Module: EmscriptenModule; runtimeId: number; @@ -403,10 +687,19 @@ type RuntimeAPI = { productVersion: string; gitHash: string; buildConfiguration: string; + wasmEnableThreads: boolean; + wasmEnableSIMD: boolean; + wasmEnableExceptionHandling: boolean; }; } & APIType; type ModuleAPI = { + /** + * The builder for the .NET runtime. + */ dotnet: DotnetHostBuilder; + /** + * Terminates the runtime "process" and reject all further calls to the API. + */ exit: (code: number, reason?: any) => void; }; type CreateDotnetRuntimeType = (moduleFactory: DotnetModuleConfig | ((api: RuntimeAPI) => DotnetModuleConfig)) => Promise; @@ -446,4 +739,4 @@ declare global { } declare const createDotnetRuntime: CreateDotnetRuntimeType; -export { AssetBehaviors, AssetEntry, CreateDotnetRuntimeType, DotnetHostBuilder, DotnetModuleConfig, EmscriptenModule, GlobalizationMode, IMemoryView, ModuleAPI, MonoConfig, ResourceRequest, RuntimeAPI, createDotnetRuntime as default, dotnet, exit }; +export { type AssetBehaviors, type AssetEntry, type CreateDotnetRuntimeType, type DotnetHostBuilder, type DotnetModuleConfig, type EmscriptenModule, GlobalizationMode, type IMemoryView, type ModuleAPI, type MonoConfig, type RuntimeAPI, createDotnetRuntime as default, dotnet, exit };