Getting Started For Dummies

[jzabroski]

Hi - Just a user experience report trying to use your library, which you may appreciate if you really want more evangelism for this project. I used to think I was just dumb and the only person on the planet who had trouble getting started with this library. But I found others expressing frustration as well.

Can you please improve the documentation for those of us who just want to add a simple Enumerable.Buffer extension method to our code instead of rolling our own?

Confusion 1

When I search for "system observable buffer" in Google, the third link is https://docs.microsoft.com/en-us/previous-versions/dotnet/reactive-extensions/hh212130(v=vs.103) (which is disclaimed by Microsoft as "We're no longer updating this content regularly. Check the Microsoft Product Lifecycle for information about how this product, service, technology, or API is supported.").

On this obsolete page, it says the following:

Namespace: System.Reactive.Linq Assembly: System.Reactive (in System.Reactive.dll)

Confusion 2

OK, so I search nuget for System.Reactive, and find a package that claims to support my runtime version. I install it. I add using System.Reactive.Linq to my C# file. But there is no AsObservable() extension method available on my enumerable.

Confusion 3

Hmm... two years ago I recall running into precisely this problem, and recall something about System.Interactive namespace (how would anyone even know to search for that if they didn't spend hours like I did years ago on this mental exercise?) I uninstall System.Reactive and install System.Interactive instead. My project now has

    <PackageReference Include="System.Interactive" Version="4.1.1" />

I go back to my C# file. I remove using System.Reactive.Linq and add try to add using System.Interactive BUT I get red ink on the Interactive. WTF - I think - how is this possible? I close Visual Studio, open it back up. Error is still there. I do a git reset, and readd System.Interactive, and still red ink. How is it I can add a nuget package and not know the root namespace of the package?

Confusion 4 - Where the hell is this method?

At the end of the day, I give up, I implement my own buffer, add my own regression tests, and move on. This project is just too hard to get started with.

As some frank advice, I suggest ditching all the stuff about portability to other platforms and focus on just a great .NET platform library. The README.md just says this random thing about Ix.NET being contained within this project, but where, and how do I get it on nuget.org, I have no idea.

[quinmars]

The AsXxxx() extension methods are just some convenient methods that are equivalent to a cast of the interface. This could look like:

public static IObservable<T> AsObservable(this IObservable<T> obs) => obs;

This is useful to reduce ambiguity for extension method resolution. For example, if you have a type that implements IObservable and IQbservable.

But what you are looking for is the ToXxxx() extension method type, namely ToObservable(). This does actually generates an adapter, so that you can plug the Ix and Rx world together.

[jzabroski]

I ended up finding Buffer(), right before I was about to give up and re-implement my own. fuget.org was helpful in showing me the namespaces used by System.Interactive package. https://www.fuget.org/packages/System.Interactive - I was surprised to see three namespaces, and guessed that it was in the System.Linq namespace.

I don't think this changes my general observation about how confusing this library is to get started with.

[SeriousM]

Confusion 2

OK, so I search nuget for System.Reactive, and find a package that claims to support my runtime version. I install it. I add using System.Reactive.Linq to my C# file.

I'm on the search of the reactive nuget I should use. There is System.Reactive (nuget update 2020) and System.Interactive (nuget update 2022). Which should I use? Is the Interactive the new Reactive but more modern? It would be awesome to cleanup this confusion in the readme. Maybe a contributor could help out?

[sgf]

My feeling with reactive is that maybe the problems I want to solve are not as complex as reactive. For example, I just want to simply monitor the changes of several variables. But reactive let me to learn many concepts. Seeing the dense introduction, I fell into panic. I'm not sure if I should continue.

For example, I often develop in winform, and reactive may not be suitable for winform, and may require the support of reactiveui. The design of reactiveui.winform has many limitations, and the code looks very awkward. Any technology has a price, and I feel like the cost of using reactive seems to be worse than if I solve the problem directly.