Skip to content

FAQ

Jump to bottom
Maziar Rezaei edited this page Feb 19, 2020 · 23 revisions
Why the extension methods are not deployed using a DLL/Assembly?

Using a DLL/Assembly can be a weak choice:

  • Most of the time, all you need are only very few methods and it does not justify a dedicated DLL and extra reference. That is why a lot of teams just copy the extension methods they usually use across projects. How many times have your colleague sent you an extension method via chat/e-mail?
  • It is an extra unnecessary addition to the deployment, especially if you need to deal with strong names and/or signing the assembly. This becomes harder to justify when you did not use the methods extensively throughout your code base.
  • If you do not have the full authority over the repository, it is usually very hard to justify such DLL reference only with the premise of "It helps me become more productive". After all, it's an assembly full of static helper functions which is a despised pattern.
  • Referencing such DLL adds in hundreds of extension methods that clutter the IntelliSense. No way to choose only what you need on a project-level basis, and no clear way to define team's coding standards around them.
  • All projects need to have a dependency on this assembly.
  • You may need to add a using statement to ALL your files to ensure available everywhere.
How ProductivityExtensionMethods tackles the problem?
  • Add the nuget package to the project(s) (such as your common library) that are referenced by all other projects. The methods will be available everywhere.
  • Referencing nuget package only adds one T4 Template file to your project. No other footprint.
  • The T4 template generates a C# file (.cs) in that project. It is a partial static class, under the default namespace of the project. By default, there is no methods in it until you choose the categories.
  • The top section of the T4 template file has a configuration that you can use to switch on only the set of the methods that you need or plan to standardize in your team.
  • When new version of this package arrives, update the package. It takes care of porting your configuration to the new version.
Can I use it without nuget? The unique way of distributing these extension methods requires the use of nuget to give distributability and updatability. However if you need the methods without nuget, I recommend downloading the nuget package file, rename .nupkg to .zip to extract it, and add the T4 template in assets folder to your project. If you do not need the T4 template, copy methods you need from here.
Why so few methods are included compared to other libraries?

The driving mindset in selection of the majority of the extension methods here is the ability to introduce them as coding guidelines within or across teams. Besides individuals' productivity, the goal is to improve the readability and maintainability of the code. This cannot be achieved if only some developers who happen to know the methods use them and the rest of the team ignore. By keeping the number of the extension methods low, and giving the ability to only enable certain categories, more developers start to use them and it will be easier to standardize the practice. Over time it becomes a team habit.

This means in future some methods may be even dropped between the major releases. This way, the library becomes leaner, and can provide improved best-practices as it evolves. In case you still need the deprecated method, keep it in a separate partial class that you will own. This is one of the advantages of distributing source code and not the binary. The Semantic Versioning practice will be followed if a method is going to be dropped.

What is the criteria for choosing the extension methods?
  1. The method should either improve readability, or reduce the number of characters needed for very frequent code fragments.
  2. Keeping the overall number of the extension methods low. Refer to previous question for details.
  3. Sharing some complex code that is very likely to be used, but are not available anywhere else on the Internet. One example is the ToHierarchy() method for converting a flat list into a hierarchy with O(n). Such criterion is not much aligned with the core philosophy. Do not expect to see many of such methods in future releases.
Which License the code is distributed under?
  • All the extension methods are provided as-is, under Unlicense. This is when you use nuget package, or just copy the extension methods you need.
  • If you fork the repo and distribute your own version, or use any code outside "AllExtensions.cs" in your project, you should follow GPL-3.0-or-later.
I like the approach, but I want to use it for my own extension methods. How?

ProductivityExtensionMethods repository is created to serve as an example of how such approach can be adopted internally to standardize framework/CMS specific methods that developers come up with over time. It provides all the tools and automation needed to create a nuget package that distribute methods via T4 template.

  • Fork the repository.
  • Replace all methods in AllExtensions.cs with your own. Categorize your methods using regions with proper names.
  • The ProductivityExtension.tt takes care of generating the final T4 template by reading AllExtensions.cs.
  • CodePreprocessor project is a console application to parse code and detect Nullable Reference Type syntax usage using Roslyn. This runs inside ProductivityExtension.tt and helps to keep compatibility if you use your methods on VS 2017, and nullable reference syntaxs are the only C# 8.0 feature you used.
  • After customizing ProductivityExtensionMethods.nuspec to meet your needs, Use MakeNugetPackage.ps1 to generate your own nuget package.
  • Publish the package to your private nuget server.
I see bugs / nuget package does not install correctly.

Please review the known issues first.

If you come across a bug in extension methods, or nuget package doesn't create .tt file, please open an issue with details.

How can I contribute? I don't see the methods that I think should be there.

Contributions are welcome through suggestions, submitting code or pull requests.

The project is currently in need of more XML documentation and automated testing.

If you are recommending extension methods, please review the selection criteria above.

For pull requests, please follow these guidelines:

  • All the comments (including on the commits) must be in English.
  • There should not be any Merge commits. Please squash such commits or use rebase to get the latest. Your changes will most likely be rebased into upstream as well.
  • Please keep your commits clean. If commits are fixing one another, they should be squashed.
  • If fixing/implementing an issue, use this comment format for the commit:
    #<Issue Number> <Issue Title>. Optional:What will the commit achieve in 2-5 words, no period
Clone this wiki locally