Writing a good library is an art and science. Assuming that you have already decided on functionality provided and exposed relevant APIs to consumers of the library it seems that one problem remained unresolved - exception handling.
In general exceptions which will be raised during library code execution could be divided into two groups:
1. Dependent on library implementation and functionality.
2. Dependent on consumer or system and out of area of interest for your library.
IMHO best practice would be to define all exceptions which are thrown by library code and derive them either from
ApplicationException or better yet from relevant .NET exception with your lib specific prefix i.e.:
<LibShortName>InvalidOperationException. Then if your library should throw exception to client code use library derived exceptions.
If there are exceptions raised outside of library and they are meaningful from your lib functionality perspective you can catch them and either throw new library exception containing as an internal exception already catched exception or use your
<LibShortName>AggregateException to create chaining of exceptions before exposing them to clients.
The above scheme is used in many popular .NET libraries i.e. SharpSkia. There are other approaches to the problem, however, I find the above one most informative for library consumers - they get as much information on error as possible. Furthermore they can easily use type based patterns in catching and handling exceptions.
One of the most important aspects of writing good libraries is performance. To get best one for you library never use exception for control flow in you code. Exceptions should be used exclusively for error conditions. One of good examples of bad design violating the above pattern was
ANTLR C# parser framewrok AFAIR v2. At some stage library was using exceptions for controlling parsing logic what was extremely inefficient. Later it was refactored to use exceptions only for error conditions improving performance by several orders of magnitude.
Finally one of the best books on designing .NET library APIs is:
- Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries by Krzysztof Cwalina and Brad Adams.
What could be an interesting read these are discussions on
API Reviews in closed and open issuess from .NET Core corefx repository and a bit old but still a classic one Krzysztof Cwalina blog posts tagged with General API Design