<commit_before># MFaaP.MFWSClient (C# M-Files Web Service Wrapper)

*Please note that this library is provided "as-is" and with no warranty, explicit or otherwise.  You should ensure that the functionality meets your requirements, and thoroughly test them, prior to using in any production scenarios.*

The following helper library is provided as work-in-progress, and may not be fully complete.

This library aims to provide an easy-to-use C# wrapper for the [M-Files Web Service](http://www.m-files.com/MFWS/), which is part of the M-Files Web Access.  The user guide contains more information on [setting up M-Files Web Access](http://www.m-files.com/user-guide/latest/eng/#Configure_M-Files_Web_Access.html).

It currently provides the following functionality:

* Authentication, both using credentials and using Windows Single Sign On
* Object creation
* File upload
* Vault extension method execution
* Searching

## Basic usage

This functionality is exposed by the `MFWSClient` object, which takes the URL of the M-Files Web Service in the constructor:

```csharp
// Instantiate a new MFWS client.
var client = new MFWSClient("http://m-files.mycompany.com");
```

The API provides both "Async" and blocking versions of most methods.  To use .NET Tasks and the async/await pattern, simply use the *Async version of the method (e.g. `AuthenticateUsingCredentialsAsync` instead of `AuthenticateUsingCredentials`).

## Authentication

Currently two methods of authentication are supported: authentication using credentials, and Windows Single Sign On.

## Authenticating using credentials

```csharp
// Instantiate a new MFWS client.
var client = new MFWSClient("http://m-files.mycompany.com");

// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24} (clear credentials).
client.AuthenticateUsingCredentials(
    Guid.Parse("{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}"),
    "MyUsername",
    "MyPassword" );
```

Note that the M-Files Web Service will provide authentication tokens even if the credentials are incorrect.  This is by design.

### Automatically expiring an authentication token

If no expiry information is provided, an authentication token will be valid indefinitely.  To set a specific expiry datetime, pass the datetime on the authentication call:

```csharp
// Instantiate a new MFWS client.
var client = new MFWSClient("http://m-files.mycompany.com");

// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24} (clear credentials).
// Set the expiry as 10am UTC on 1st January 2017.
client.AuthenticateUsingCredentials(
    Guid.Parse("{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}"),
    "MyUsername",
    "MyPassword",
    new DateTime(2017, 01, 01, 10, 00, 00, DateTimeKind.Utc) );
```

Alternatively, to expire after a specified time from the initial authentication, provide a TimeSpan when authenticating:

```csharp
// Instantiate a new MFWS client.
var client = new MFWSClient("http://m-files.mycompany.com");

// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24} (clear credentials).
// Set the expiry as 1 hour from initial authentication.
client.AuthenticateUsingCredentials(
    Guid.Parse("{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}"),
    "MyUsername",
    "<PASSWORD>",
    TimeSpan.FromHours(1) );
```


## Authenticating using Windows Single Sign On

If using Windows Single Sign On, the application will use the current Windows identity that it is running under.  Note that [using Windows Single Sign On requires additional configuration](https://partners.cloudvault.m-files.com/Default.aspx?#CE7643CB-C9BB-4536-8187-707DB78EAF2A/object/75F59ED5-CC7F-4A0A-90D5-0F582D26E884/latest).

```csharp
// Instantiate a new MFWS client.
var client = new MFWSClient("http://m-files.mycompany.com");

// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24} (clear credentials).
client.AuthenticateUsingSingleSignOn( Guid.Parse("{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}") );
```

## Searching

### Quick search

Simple searching can be done using the `SearchForObjectsByString` method.

Note that the search will only return items which you have access to, so ensure that you are authenticated (if required) prior to executing the method.

```csharp
// Connect to the online knowledgebase.
// Note that this doesn't require authentication.
var client = new MFWSClient("http://kb.cloudvault.m-files.com");

// Execute a simple search for the word "mfws".
var results = client.ObjectSearchOperations.SearchForObjectsByString("mfws");

// Iterate over the results and output them.
System.Console.WriteLine($"There were {results.Length} results returned.");
foreach (var objectVersion in results)
{
	System.Console.WriteLine($"\t{objectVersion.Title}");
	System.Console.WriteLine($"\t\tType: {objectVersion.ObjVer.Type}, ID: {objectVersion.ObjVer.ID}");<commit_msg>Removed incorrect wording from sample.<commit_after># MFaaP.MFWSClient (C# M-Files Web Service Wrapper)

*Please note that this library is provided "as-is" and with no warranty, explicit or otherwise.  You should ensure that the functionality meets your requirements, and thoroughly test them, prior to using in any production scenarios.*

The following helper library is provided as work-in-progress, and may not be fully complete.

This library aims to provide an easy-to-use C# wrapper for the [M-Files Web Service](http://www.m-files.com/MFWS/), which is part of the M-Files Web Access.  The user guide contains more information on [setting up M-Files Web Access](http://www.m-files.com/user-guide/latest/eng/#Configure_M-Files_Web_Access.html).

It currently provides the following functionality:

* Authentication, both using credentials and using Windows Single Sign On
* Object creation
* File upload
* Vault extension method execution
* Searching

## Basic usage

This functionality is exposed by the `MFWSClient` object, which takes the URL of the M-Files Web Service in the constructor:

```csharp
// Instantiate a new MFWS client.
var client = new MFWSClient("http://m-files.mycompany.com");
```

The API provides both "Async" and blocking versions of most methods.  To use .NET Tasks and the async/await pattern, simply use the *Async version of the method (e.g. `AuthenticateUsingCredentialsAsync` instead of `AuthenticateUsingCredentials`).

## Authentication

Currently two methods of authentication are supported: authentication using credentials, and Windows Single Sign On.

## Authenticating using credentials

```csharp
// Instantiate a new MFWS client.
var client = new MFWSClient("http://m-files.mycompany.com");

// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24} (clear credentials).
client.AuthenticateUsingCredentials(
    Guid.Parse("{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}"),
    "MyUsername",
    "MyPassword" );
```

Note that the M-Files Web Service will provide authentication tokens even if the credentials are incorrect.  This is by design.

### Automatically expiring an authentication token

If no expiry information is provided, an authentication token will be valid indefinitely.  To set a specific expiry datetime, pass the datetime on the authentication call:

```csharp
// Instantiate a new MFWS client.
var client = new MFWSClient("http://m-files.mycompany.com");

// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24} (clear credentials).
// Set the expiry as 10am UTC on 1st January 2017.
client.AuthenticateUsingCredentials(
    Guid.Parse("{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}"),
    "MyUsername",
    "<PASSWORD>",
    new DateTime(2017, 01, 01, 10, 00, 00, DateTimeKind.Utc) );
```

Alternatively, to expire after a specified time from the initial authentication, provide a TimeSpan when authenticating:

```csharp
// Instantiate a new MFWS client.
var client = new MFWSClient("http://m-files.mycompany.com");

// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24} (clear credentials).
// Set the expiry as 1 hour from initial authentication.
client.AuthenticateUsingCredentials(
    Guid.Parse("{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}"),
    "MyUsername",
    "MyPassword",
    TimeSpan.FromHours(1) );
```


## Authenticating using Windows Single Sign On

If using Windows Single Sign On, the application will use the current Windows identity that it is running under.  Note that [using Windows Single Sign On requires additional configuration](https://partners.cloudvault.m-files.com/Default.aspx?#CE7643CB-C9BB-4536-8187-707DB78EAF2A/object/75F59ED5-CC7F-4A0A-90D5-0F582D26E884/latest).

```csharp
// Instantiate a new MFWS client.
var client = new MFWSClient("http://m-files.mycompany.com");

// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24}.
client.AuthenticateUsingSingleSignOn( Guid.Parse("{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}") );
```

## Searching

### Quick search

Simple searching can be done using the `SearchForObjectsByString` method.

Note that the search will only return items which you have access to, so ensure that you are authenticated (if required) prior to executing the method.

```csharp
// Connect to the online knowledgebase.
// Note that this doesn't require authentication.
var client = new MFWSClient("http://kb.cloudvault.m-files.com");

// Execute a simple search for the word "mfws".
var results = client.ObjectSearchOperations.SearchForObjectsByString("mfws");

// Iterate over the results and output them.
System.Console.WriteLine($"There were {results.Length} results returned.");
foreach (var objectVersion in results)
{
	System.Console.WriteLine($"\t{objectVersion.Title}");
	System.Console.WriteLine($"\t\tType: {objectVersion.ObjVer.Type}, ID: {objectVersion.ObjVer.ID}");
{'fraction_non_alphanumeric': 0.10104027191265835, 'fraction_numerical': 0.045730765269337725, 'mean_word_length': 4.772889417360285, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 2, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7469253', 'n_tokens_mistral': 3215, 'n_tokens_neox': 2945, 'n_words': 1011}