MFiles.Grpc 26.11.0

M-Files gRPC API client for .NET

The NuGet package MFiles.Grpc for the M-Files gRPC API, with runnable examples: a quickstart and one program per task recipe. The guides on developer.m-files.com embed their code.

The generated classes and the helpers are in the namespace MFiles.Grpc: messages such as SearchObjectsRequest, one client per service, such as IRPCSearch.IRPCSearchClient, and MFilesConnection. The connection does what the protos cannot say: it opens the channel (TLS or not, an optional custom root certificate, the message size limits of M-Files' own client), adds the M-Files call metadata to every call, logs in and out (with a password, a token or through the browser), decodes errors into MFilesException and reads the vault's metadata structure version.

The package is a preview: its helpers can still change between releases.

Install

From NuGet, the version for your server (see Versions):

dotnet add package MFiles.Grpc

Or build from this folder with the .NET SDK 10 or later. Grpc.Tools generates the client classes from the protos when MFiles.Grpc builds; it finds them in this order:

1. the MFILES_PROTO_DIR environment variable: the folder that contains mfiles/structs.proto;
2. proto/ in this folder;
3. ../../proto, where the API bundle keeps them next to samples/;
4. src/Build/IDL/Docs/out/grpc-api-docs/proto when the samples run inside the M-Files repository.

Packages (pinned in src/MFiles.Grpc/MFiles.Grpc.csproj): Grpc.Net.Client 2.85.0, Google.Protobuf 3.36.2 and Grpc.Tools 2.85.0 (build time only).

Configure

MFilesSettings.FromEnvironment() and the examples read environment variables:

$env:MFILES_ADDRESS = 'localhost:7766'
$env:MFILES_TLS = 'false'
$env:MFILES_VAULT = '{7BBEA0BC-40D8-4BCB-A67D-8A3ACFBDB575}'
$env:MFILES_USERNAME = 'alice'
$env:MFILES_PASSWORD = Read-Host -Prompt 'Password'

Examples

dotnet run --project examples\Quickstart
dotnet run --project examples\Recipes -- search 1 30 10

The defaults suit the M-Files Sample Vault. Recipes that write create documents whose titles start with [docs-test] and delete them at the end unless you pass --keep.

Tests

dotnet test tests\MFiles.Grpc.Tests      # unit tests; no server needed
.\run-tests.ps1                          # the unit tests, then every example against a vault
.\run-tests.ps1 -Recipe search, paging

run-tests.ps1 builds the solution, runs the unit tests, the quickstart and every recipe except login-service, and fails if any of them fails. It reads the connection from %USERPROFILE%\.mfiles-grpc-docs\test-config.json (section local by default), so no credentials are kept in the repository.

Versions

There is one package version per M-Files Server release: 26.11.0 is for 26.11, 26.11.1 a revision of it. A version works with its server release and later ones; with an older server, methods that the server does not have fail with Unimplemented.

License

MIT; see LICENSE.