This page is for documentation, guides, and comments on my open source Fluent Interface Creator program.
What is a “fluent interface”?
If you aren’t familiar with fluent interfaces, and why you might want to use them, you can read more about them in this article on “How to create a fluent interface in C#“, or by watching a webinar I did for PostSharp on Making Your Code Mistake-Proof with Fluent Interfaces.
Here is a quick example of the code to create am email object in C#, using normal coding and using a fluent interface.
C# code to send an email (standard method)
using System.Net.Mail; namespace Engine.Email.WithoutFI { public class CallingClass { public void MyFunction() { MailMessage email = new MailMessage(); email.From = new MailAddress("sender@mysite.com"); email.To.Add("toreceiver@mysite.com"); email.CC.Add("ccreceiver@mysite.com"); email.Bcc.Add("bccreceiver@mysite.com"); email.Subject = "This is the subject"; email.Body = "This is the body of the email."; SmtpClient smtpClient = new SmtpClient("smtp host"); smtpClient.Send(email); } } }
C# code to send an email (with a fluent interface)
namespace Engine.Email.WithFI { public class CallingClass { public void MyFunction() { FluentEmail .CreateEmail() .UsingSmtpServer("smtp host") .From("sender@mysite.com") .To("toreceiver@mysite.com") .CC("ccreceiver@mysite.com") .BCC("bccreceiver@mysite.com") .WithSubject("This is the subject") .WithBody("This is the body of the email.") .Send(); } } }
Besides creating code that is easier to read, a fluent interface can be used to ensure all required parameters are set – before you execute the final function that depends on those parameters.
Requirements to run Fluent Interface Creator
This program is written using Visual Studio Community Edition 2015. The source code is in C#, using the .NET Framework 4.5.2. The front-end is written using WPF.
This should work on any Windows computer with .NET Framework 4.5.2 installed.
How to use Fluent Interface Creator
Creating a new fluent interface project
On the menu, click File -> Create New Project.
On the “Project Settings” tab, enter the name of your project, the namespace where the fluent interface class/interfaces will be located, and the name of the class for the fluent interface builder. The “Factory Class Name” defaults to the “Project Name” value, with spaces removed and a “Builder” suffix. You can overwrite this value, if you want.
Adding custom datatypes
If the functions in your fluent interface will need to use non-standard datatypes (for parameters, or return values), you can add them on this screen.
The datatype namespace will be used to create the “using” references for the fluent interface files.
Adding the methods
The datagrids on the left show the methods for your fluent interface – separated by “Instantiating”, “Chaining”, and “Executing” methods. (see “How to create a fluent interface in C#“, if you are not familiar with how those are different).
To add a new method, use the controls on the right of the screen.
Select the method’s group (Instantiating, Chaining, or Executing), and enter its name. If the method is an Executing method, you must also select its return datatype – “void” is one of the options.
If the function needs to accept any parameters, you must add its parameters (inside the Parameters box), before you can save the method.
When you have entered all the method’s information, click on the “Save Method” button. If the data is valid, and the method does not match an existing method, it will be saved.
NOTE: Currently (version 1.0.0), you cannot edit methods or parameters that you add. You can only delete them and re-add them. This is one of the first things I want to change for the next version.
Also, if you add or delete methods, you will need to reset the calling order and interface names – on the other tabs.
Set Calling Order
After the methods have been entered, you need to define which methods can be called, in which order. This is what builds the fluent interface’s “grammar” – its ability to force the called methods.
Click the “Select” button for each method in the upper grid. The methods that can possibly be called next are displayed in the bottom half of the screen. Check each one that you want to be able to call immediately after calling the method selected from the top datagrid.
Name Interfaces
After all the calling orders have been set, go to the “Name Interfaces” tab.
There will be a row for each interface that needs to be created. Their names will be blank, to start.
Click on each row’s “Select” button. The methods that use this interface, and the methods that can be called in this interface, will be displayed on the right side of the screen. Enter a unique interface name here, and click the “Save” button.
Create Fluent Interface File(s)
When all the interface names have been entered, you can go to the “Create Fluent Interface File(s)” tab.
Click on the “Create fluent interface files” button.
On the left side of the screen will be a single-file version of the fluent interface code. The interfaces are included in the same file as the fluent interface builder class.
On the right side of the screen are the individual files.
Underneath each section is a “Save to disk” button, to write the file(s) to disk.
NOTE: The fluent interface builder class has empty versions of the methods. You will need to manually add in the code for those functions: saving values to private variables (for the chaining methods), or the code that needs to be performed in the executing functions.
Saving your fluent interface project
The “Save” button, in the lower-right of the screen, will save your project’s values to a .ficp (Fluent Interface Creator Project) file.
You can load your saved data using the menu option File -> Load Project.
Planned enhancements
- Ability to edit values (instead of deleting and adding updated values)
- Better UI – especially with adding method parameters
- Ability to re-order method parameters (instead of deleting and re-adding)
- Create fluent interface files in VB.NET, and other languages
- Remove “void” as a parameter datatype
- IsDirty indicator, to prevent closing or creating a new project without saving your changes
- Unit tests
- Versioned serializer/de-serializer
- Only able to create the files if all data is entered, valid, and used (no “orphaned” methods)
- Keep existing interface names, when adding newly-added functions do not invalidate them
- Add “Help” screen
- Option to check for updated version
Source code
https://github.com/ScottLilly/FluentInterfaceCreator
Comments
If you have any comments, questions, feature requests, etc., please leave a comment below.
Hello Scott
I tried to add the following data type in fluent interface creator:
Name: IEnumerable
Namespace: System.Collections
but it tells me that “‘Namespace’ cannot contain special characters”.
The only special character is the dot.
Do I understand/operate something incorrectly or is that a bug in the tool?
Best regards
Chris
Hi Chris,
That is a bug. THank you for letting me know about it. The special character validation is supposed to prevent characters like %$#. But, it’s also catching “.”, which is valid (if we apply some additional rules, like not allowing “.” as the first characters, not allowing more than one in a row, etc.).
For now, you can fix it by editing the Datatype class in Engine.Models. Change the validation check on line 65 to the code below. NOTE: This does not remove any “.”s from the property value. It only removes them from the value that is passed into the validation extension method.
if(ContainingNamespace.Replace(".", "").ContainsInvalidCharacter())
{
yield return ErrorMessages.NamespaceCannotContainSpecialCharacters;
}
I’ll work on a better solution and upload a fix to the program – although it will might be a few days, since I have a project to deliver Wednesday.
I just pushed an update to GitHub with the fix. I also added validation for Project.FactoryClassName (it’s required now) and FactoryClassNamespace (using the same rules as the datatype namespace). Please let me know if you try it and see any problems.
Hi, id the final “FluentEmailBuilder.cs” file available, I cant get it to work and would like to see how it should be.
Hi Magnus,
I could not find a copy of the FluentEmailBuilder class. You can see the manual steps to create a fluent interface here: https://www.scottlilly.com/how-to-create-a-fluent-interface-in-c/