{"id":13600404,"url":"https://github.com/M-Files/Libraries.MFWSClient","last_synced_at":"2025-04-11T00:31:19.987Z","repository":{"id":38102635,"uuid":"245131989","full_name":"M-Files/Libraries.MFWSClient","owner":"M-Files","description":"An example .NET wrapper for the M-Files Web Service.","archived":false,"fork":false,"pushed_at":"2024-09-18T12:18:36.000Z","size":4144,"stargazers_count":14,"open_issues_count":5,"forks_count":12,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-10T01:12:50.945Z","etag":null,"topics":["community","example","nuget","wrapper"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/M-Files.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-05T10:22:59.000Z","updated_at":"2024-09-18T12:17:14.000Z","dependencies_parsed_at":"2023-01-23T20:00:13.081Z","dependency_job_id":"35a242f0-fcea-45dc-8c34-ac09ff39f359","html_url":"https://github.com/M-Files/Libraries.MFWSClient","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/M-Files%2FLibraries.MFWSClient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/M-Files%2FLibraries.MFWSClient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/M-Files%2FLibraries.MFWSClient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/M-Files%2FLibraries.MFWSClient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/M-Files","download_url":"https://codeload.github.com/M-Files/Libraries.MFWSClient/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137891,"owners_count":21053775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["community","example","nuget","wrapper"],"created_at":"2024-08-01T18:00:38.467Z","updated_at":"2025-04-11T00:31:19.964Z","avatar_url":"https://github.com/M-Files.png","language":"C#","readme":"# MFaaP.MFWSClient (C# M-Files Web Service Wrapper)\n\n*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.*\n\nThe following helper library is provided as work-in-progress, and may not be fully complete.\n\nThis 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).\n\nIt currently provides the following functionality:\n\n* Authentication, both using credentials and using Windows Single Sign On\n* Object creation\n* File upload\n* Vault extension method execution\n* Searching\n\n## Nuget package\n\nThis library is available [via nuget](https://www.nuget.org/packages/MFaaP.MFWSClient).  The simplest way to get started with this library is to add the `MFaaP.MFWSClient` package to your class library.  .NET Framework 4.6 (and higher) and .NET Standard 2.0 runtimes are supported.\n\n## Basic usage\n\nThis functionality is exposed by the `MFWSClient` object, which takes the URL of the M-Files Web Service in the constructor:\n\n```csharp\n// Instantiate a new MFWS client.\nvar client = new MFWSClient(\"http://m-files.mycompany.com\");\n```\n\nThe 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`).\n\n## Authentication\n\nCurrently three methods of authentication are supported: authentication using credentials, and Windows Single Sign On.\n\n## Authenticating using credentials\n\n```csharp\n// Instantiate a new MFWS client.\nvar client = new MFWSClient(\"http://m-files.mycompany.com\");\n\n// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24} (clear credentials).\nclient.AuthenticateUsingCredentials\n(\n    Guid.Parse(\"{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}\"),\n    \"MyUsername\",\n    \"MyPassword\",\n\tGuid.NewGuid.ToString() // Providing a session ID allows logout.\n);\n```\n\nNote that the M-Files Web Service will provide authentication tokens even if the credentials are incorrect.  This is by design.\n\n### Automatically expiring an authentication token\n\nIf 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:\n\n```csharp\n// Instantiate a new MFWS client.\nvar client = new MFWSClient(\"http://m-files.mycompany.com\");\n\n// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24} (clear credentials).\n// Set the expiry as 10am UTC on 1st January 2017.\nclient.AuthenticateUsingCredentials\n(\n    Guid.Parse(\"{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}\"),\n    \"MyUsername\",\n    \"MyPassword\",\n    new DateTime(2017, 01, 01, 10, 00, 00, DateTimeKind.Utc)\n);\n```\n\nAlternatively, to expire after a specified time from the initial authentication, provide a TimeSpan when authenticating:\n\n```csharp\n// Instantiate a new MFWS client.\nvar client = new MFWSClient(\"http://m-files.mycompany.com\");\n\n// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24} (clear credentials).\n// Set the expiry as 1 hour from initial authentication.\nclient.AuthenticateUsingCredentials(\n    Guid.Parse(\"{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}\"),\n    \"MyUsername\",\n    \"MyPassword\",\n    TimeSpan.FromHours(1) );\n```\n\n\n## Authenticating using Windows Single Sign On\n\nIf 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).\n\n```csharp\n// Instantiate a new MFWS client.\nvar client = new MFWSClient(\"http://m-files.mycompany.com\");\n\n// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24}.\nclient.AuthenticateUsingSingleSignOn( Guid.Parse(\"{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}\") );\n```\n\n## Authenticating using OAuth 2.0\n\nConnecting using OAuth 2.0 requires several steps:\n\n1. Call `MFWSClient.GetOAuth2Configuration`.  If this returns null then OAuth 2.0 is not configured.\n2. Open a web browser and navigate to `OAuth2Configuration.GenerateAuthorizationUri`.\n3. Handle any redirects that occur within the web browser.  If the redirected URI **does not** start with `OAuth2Configuration.GetAppropriateRedirectUri` then allow it to occur.\n4. For redirects that **do** start with `OAuth2Configuration.GetAppropriateRedirectUri`, call `MFWSClient.GenerateTokensFromOAuthRedirect`.  Note that this may throw an exception if the login failed.\n\n## Searching\n\n### Quick search\n\nSimple searching can be done using the `SearchForObjectsByString` method.\n\nNote 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.\n\n```csharp\n// Connect to the online knowledgebase.\n// Note that this doesn't require authentication.\nvar client = new MFWSClient(\"http://kb.cloudvault.m-files.com\");\n\n// Execute a simple search for the word \"mfws\".\nvar results = client.ObjectSearchOperations.SearchForObjectsByString(\"mfws\");\n\n// Iterate over the results and output them.\nSystem.Console.WriteLine($\"There were {results.Length} results returned.\");\nforeach (var objectVersion in results)\n{\n\tSystem.Console.WriteLine($\"\\t{objectVersion.Title}\");\n\tSystem.Console.WriteLine($\"\\t\\tType: {objectVersion.ObjVer.Type}, ID: {objectVersion.ObjVer.ID}\");\n}\n```\n\n### Advanced / complex search\n\nIn addition to a simple quick search, the helper library allows the execution of more complex, or \"advanced\" searches using the `Search` method.  This method accepts a collection of `ISearchCondition` objects which can be used to further constrain any search.\n\nNote 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.\n\n```csharp\n// Connect to the online knowledgebase.\n// Note that this doesn't require authentication.\nvar client = new MFWSClient(\"http://kb.cloudvault.m-files.com\");\n\n// Execute an advanced search for the word \"mfws\", restricted to object type 0 (documents), which have a Document Date (property 1002) greater than 2015-11-01.\nvar results = client.ObjectSearchOperations.SearchForObjectsByConditions(\n\tnew QuickSearchCondition(\"mfws\"),\n\tnew ObjectTypeSearchCondition(0),\n\tnew DatePropertyValueSearchCondition(1002, new DateTime(2015, 11, 01), SearchConditionOperators.GreaterThan)\n);\n\n// Iterate over the results and output them.\nSystem.Console.WriteLine($\"There were {results.Length} results returned.\");\nforeach (var objectVersion in results)\n{\n\tSystem.Console.WriteLine($\"\\t{objectVersion.Title}\");\n\tSystem.Console.WriteLine($\"\\t\\tType: {objectVersion.ObjVer.Type}, ID: {objectVersion.ObjVer.ID}\");\n}\n```\n\n\n\n#### Restricting by text properties\n\nFor example, to restrict the search results by the value of a property with ID `1002`:\n\n*Note that the library will handle ensuring items are correctly encoded.**\n\n```csharp\n// Create our search condition.\nvar condition = new TextPropertyValueSearchCondition(1002, \"ESTT\");\n```\n\nIf we wished to restrict by a text property with ID where the field contains `ESTT`, we would alter the operator:\n\n```csharp\n// Create our search condition.\nvar condition = new TextPropertyValueSearchCondition(1002, \"ESTT\", SearchConditionOperators.Contains);\n```\n\nIf we wished to restrict by a text property with ID where the field matches a [wildcard search for `ESTT*`](http://www.m-files.com/user-guide/latest/eng/#Quick_search.html), we would alter the operator:\n\n```csharp\n// Create our search condition.\nvar condition = new TextPropertyValueSearchCondition(1002, \"ESTT\", SearchConditionOperators.MatchesWildcard);\n```\n\n#### Restricting by a boolean property\n\nTo restrict the search results by the value of a boolean property with ID `1050`:\n\n```csharp\n// Create our search condition.\nvar condition = new BooleanPropertyValueSearchCondition(1050, true);\n```\n\nAlternatively, we could search for only objects where the property is false:\n\n```csharp\n// Create our search condition.\nvar condition = new BooleanPropertyValueSearchCondition(1050, false);\n```\n\n#### Restricting by a numeric property (integer or real)\n\nTo restrict the search results by the value of a numeric property with ID `1100`:\n\n```csharp\n// Create our search condition.\nvar condition = new NumericPropertyValueSearchCondition(1100, 123);\n```\n\nAlternatively, we could make use of a [different operator](#operators) to instead search for objects where the value is greater than 1000:\n\n```csharp\n// Create our search condition.\nvar condition = new NumericPropertyValueSearchCondition(1100, 1000, SearchConditionOperators.GreaterThan);\n```\n\n#### Restricting by a date/time or timestamp property\n\nTo restrict the search results by the value of a date property with ID `1200`:\n\n```csharp\n// Create our search condition.\nvar condition = new DatePropertyValueSearchCondition(1200, new DateTime(2017, 6, 1));\n```\n\nAlternatively, we could make use of a [different operator](#operators) to instead search for objects where the date is newer than 1st June 2017:\n\n```csharp\n// Create our search condition.\nvar condition = new DatePropertyValueSearchCondition(1200, new DateTime(2017, 6, 1), SearchConditionOperators.GreaterThan);\n```\n\n#### Restricting by a lookup (single-select) property\n\nTo restrict the search results by the value of a single-select lookup property with ID `1500` that reference an object or value list item with ID 12345:\n\n```csharp\n// Create our search condition.\nvar condition = new LookupPropertyValueSearchCondition(1500, 12345);\n```\n\n#### Restricting by a multi-select lookup property\n\nTo restrict the search results by the value of a single-select lookup property with ID `1500` that reference an object or value list item with ID 12345:\n\n*If there is only one value then this is the same as a single-select-lookup.*\n\n```csharp\n// Create our search condition.\nvar condition = new MultiSelectLookupPropertyValueSearchCondition(1500, 12345);\n```\n\nTo restrict objects to only objects which reference objects or value list items with *either* IDs 1, 2, 3, or 4:\n\n```csharp\n// Create our search condition.\nvar condition = new MultiSelectLookupPropertyValueSearchCondition(1500, new [] { 1, 2, 3, 4 });\n```\n\n## Executing Vault Extension Methods\n\n[Vault Extension Methods](http://developer.m-files.com/Built-In/VBScript/Vault-Extension-Methods/) are named sections of code, loaded into the M-Files vault, that can be executed using the M-Files API(s).  Vault Extension Methods can be executed using the [M-Files REST API](http://developer.m-files.com/APIs/REST-API/Vault-Extension-Methods/) by executing a correctly-formatted HTTP request.\n\nThe wrapper API exposes extension methods in a similar manner as the [COM API](https://www.m-files.com/api/documentation/latest/index.html#MFilesAPI~VaultExtensionMethodOperations~ExecuteVaultExtensionMethod.html):\n\n```csharp\n// Instantiate a new MFWS client.\nvar client = new MFWSClient(\"http://m-files.mycompany.com\");\n\n// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24} (clear credentials).\nclient.AuthenticateUsingCredentials(Guid.Parse(\"{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}\"), \"MyUsername\", \"MyPassword\")\n\n// Execute an extension method with the name \"MyExtensionMethod\", passing it the input string of \"MyInputValue\".\nvar output = client.ExtensionMethodOperations.ExecuteVaultExtensionMethod(\"MyExtensionMethod\", \"MyInputValue\");\n```\n\n## Creating objects\n\n## Creating a new object\n\n### Without files\n\nThis process can be used to create objects of any type (Document or anything else) that do not contain files.  The sample below shows a Document object being created\n\n```csharp\n// Instantiate a new MFWS client.\nvar client = new MFWSClient(\"http://m-files.mycompany.com\");\n\n// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24} (clear credentials).\nclient.AuthenticateUsingCredentials(Guid.Parse(\"{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}\"), \"MyUsername\", \"MyPassword\")\n\n//Create an ObjectCreationInfo containing the properties of the new object\nvar newObjectDetails = new ObjectCreationInfo()\n{\n\t// Create the property values for the new object.\n\tPropertyValues = new[] {\n\t\tnew PropertyValue() {\n\t\t\tPropertyDef = 100, // Built-in property definition of \"class\".\n\t\t\tTypedValue = new TypedValue()\n\t\t\t{\n\t\t\t\tDataType = MFDataType.Lookup,\n\t\t\t\tLookup = new Lookup()\n\t\t\t\t{\n\t\t\t\t\tItem = 0, // The id 0 is the default Document class lookup ID\n\t\t\t\t\tVersion = -1\n\t\t\t\t}\n\t\t\t}\n\t\t},\n\t\tnew PropertyValue()\n\t\t{\n\t\t\t// Property value 22 (\"Single File Object\") is required when creating a Document Object\n\t\t\tPropertyDef = 22,\n\t\t\tTypedValue = new TypedValue()\n\t\t\t{\n\t\t\t\tDataType = MFDataType.Boolean,\n\t\t\t\tValue = false // false = \"multi-file-document\" (it is not a SINGLE file document as it has zero files)\n\t\t\t}\n\t\t},\n\t\tnew PropertyValue()\n\t\t{\n\t\t\tPropertyDef = 0, // Property definition 0 (Name or Title) is the default title property\n\t\t\tTypedValue = new TypedValue()\n\t\t\t{\n\t\t\t\tDataType = MFDataType.Text,\n\t\t\t\tValue = \"Sample Title\"\n\t\t\t}\n\t\t}\n\t}\n};\n\n// Create the object in the M-Files vault and return data about the new object.\nvar newObjectVersion = client.ObjectOperations.CreateNewObject(\n\t\t\t\t\t\t0, // 0 is the built-in object type of \"Document\"\n\t\t\t\t\t\tnewObjectDetails);\n```\n\n## Checking an object in and out.\n\n```csharp\n// Instantiate a new MFWS client.\nvar client = new MFWSClient(\"http://m-files.mycompany.com\");\n\n// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24} (clear credentials).\nclient.AuthenticateUsingCredentials(Guid.Parse(\"{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}\"), \"MyUsername\", \"MyPassword\")\n\n// Check out the document (type ID 0) with ID 567.\nvar objID = new MFaaP.MFWSClient.ObjID()\n{\n\tType = 0,\n\tID = 567\n};\nvar obj = client.ObjectOperations.CheckOut(objID);\n\n// Make a change to the object.\nclient.ObjectPropertyOperations.SetProperty(obj.ObjVer, new PropertyValue()\n{\n\tPropertyDef = 1088, // The property ID 1088.\n\tTypedValue = new MFaaP.MFWSClient.TypedValue()\n\t{\n\t\tDataType = MFDataType.Text,\n\t\tValue = \"hello world\"\n\t}\n});\n\n// Check the object back in.\nclient.ObjectOperations.CheckIn(obj.ObjVer);\n```\n\n### Undoing a checkout\n\n```csharp\n// Instantiate a new MFWS client.\nvar client = new MFWSClient(\"http://m-files.mycompany.com\");\n\n// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24} (clear credentials).\nclient.AuthenticateUsingCredentials(Guid.Parse(\"{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}\"), \"MyUsername\", \"MyPassword\")\n\n// Check out the document (type ID 0) with ID 567.\nvar objID = new MFaaP.MFWSClient.ObjID()\n{\n\tType = 0,\n\tID = 567\n};\nvar obj = client.ObjectOperations.CheckOut(objID);\n\n// Undo the checkout.\nclient.ObjectOperations.UndoCheckout(obj.ObjVer);\n```\n\n## Modifying object properties\n\n### Updating properties\n\n```csharp\n// Instantiate a new MFWS client.\nvar client = new MFWSClient(\"http://m-files.mycompany.com\");\n\n// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24} (clear credentials).\nclient.AuthenticateUsingCredentials(Guid.Parse(\"{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}\"), \"MyUsername\", \"MyPassword\")\n\n// Check out the document (type ID 0) with ID 567.\nvar objID = new MFaaP.MFWSClient.ObjID()\n{\n\tType = 0,\n\tID = 567\n};\nvar obj = client.ObjectOperations.CheckOut(objID);\n\n// Update a property on the object.\nclient.ObjectPropertyOperations.SetProperty(obj.ObjVer, new PropertyValue()\n{\n\tPropertyDef = 1088, // The property ID 1088.\n\tTypedValue = new MFaaP.MFWSClient.TypedValue()\n\t{\n\t\tDataType = MFDataType.Text,\n\t\tValue = \"hello world\"\n\t}\n});\n\n// Check the object back in.\nclient.ObjectOperations.CheckIn(obj.ObjVer);\n```\n\n### Removing properties\n\n```csharp\n// Instantiate a new MFWS client.\nvar client = new MFWSClient(\"http://m-files.mycompany.com\");\n\n// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24} (clear credentials).\nclient.AuthenticateUsingCredentials(Guid.Parse(\"{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}\"), \"MyUsername\", \"MyPassword\")\n\n// Check out the document (type ID 0) with ID 567.\nvar objID = new MFaaP.MFWSClient.ObjID()\n{\n\tType = 0,\n\tID = 567\n};\nvar obj = client.ObjectOperations.CheckOut(objID);\n\n// Remove the property from the object.\nclient.ObjectPropertyOperations.RemoveProperty(obj.ObjVer, 1088);\n\n// Check the object back in.\nclient.ObjectOperations.CheckIn(obj.ObjVer);\n```\n\n## Deleting and undeleting an object\n\n### Deleting\n\n```csharp\n// Instantiate a new MFWS client.\nvar client = new MFWSClient(\"http://m-files.mycompany.com\");\n\n// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24} (clear credentials).\nclient.AuthenticateUsingCredentials(Guid.Parse(\"{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}\"), \"MyUsername\", \"MyPassword\")\n\n// Delete the document (type ID 0) with ID 567.\nvar objID = new MFaaP.MFWSClient.ObjID()\n{\n\tType = 0,\n\tID = 567\n};\nclient.ObjectOperations.DeleteObject(objID);\n```\n\n### Undeleting\n\n```csharp\n// Instantiate a new MFWS client.\nvar client = new MFWSClient(\"http://m-files.mycompany.com\");\n\n// Authentiate to a vault with GUID {C840BE1A-5B47-4AC0-8EF7-835C166C8E24} (clear credentials).\nclient.AuthenticateUsingCredentials(Guid.Parse(\"{C840BE1A-5B47-4AC0-8EF7-835C166C8E24}\"), \"MyUsername\", \"MyPassword\")\n\n// Delete the document (type ID 0) with ID 567.\nvar objID = new MFaaP.MFWSClient.ObjID()\n{\n\tType = 0,\n\tID = 567\n};\nclient.ObjectOperations.UndeleteObject(objID);\n```","funding_links":[],"categories":["Development"],"sub_categories":["Libraries and open source"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FM-Files%2FLibraries.MFWSClient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FM-Files%2FLibraries.MFWSClient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FM-Files%2FLibraries.MFWSClient/lists"}