-
Notifications
You must be signed in to change notification settings - Fork 259
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve documentation #397
Comments
@knuxbbs Thanks for your constructive feedback. After I took over this project from toddams, I did not know all the legacy stuff hanging around.
Technically, there is a In my opinion, RazorLight.Precompile should:
However, without step 2, step 1 is kind of pointless because it will create a lot of frustrated users wondering why something doesn't work. If you are interested in digging into this, that would be super helpful.
That is not a requirement, but the README.md does explicitly steer people towards using Can you give me some wording you have in mind to clarify things?
Well, this is not strictly necessary. RazorLightEngine just wraps the callback for injected services. But yes, if you don't implement the callback options yourself using some alternative to RazorLightEngine, injected services won't work.
Agree, page is out of date, should be marked as obsolete and only useful for RazorLight 1.x. |
@maxbanas I wonder if we can detect when the stack trace can't decode |
@jzabroski I've only compiled/rendered templates using the "normal" API (RazorLightEngine via the builder), so I'm not very familiar with the other services/components in a standalone context. Do you know what entry point people would use when bypassing these? |
@maxbanas People use IEngineHandler directly, since its a thin wrapper around the Razor compiler. The RazorLightEngine is the project system, and value added callbacks like |
See #317 where I just closed a bug which really only occurred because I was trying to handle the scenario where people call IEngineHandler directly and wonder why AddRazorLight doesnt work for them. |
A documentation page like this would be very good: https://antaris.github.io/RazorEngine/AboutRazor.html |
I'm not clear. I'm not looking to rewrite Microsoft documents on what Razor is. What do you find very good about this page? |
When I create the engine handler in a way that doesn't add the inject pre-render callback, I don't see any exception being thrown until I try to use the object that was supposed to be injected. In that case I just get a NullReferenceException. It looks to me like If that's the case, and people are having issues, we could grab all the runtime properties with inject attributes (the same way PropertyInjector does) and check to make sure they're not null before calling page.ExecuteAsync() or right after ExecutePageCallbacks(). If the inject callback was it's own property (i.e. not in |
@jzabroski thank you so much for your work on this. I'm a little confused about how to install this component, perhaps you could give some tips and I could help update your docs. Project: .Net Framework 4.7.1 (eventually will be .Net Core 5, but we're updating all our libs first)
Any guidance would be hugely appreciated. |
I need to push out rc3. Really I need to setup Github actions. It's just sitting on my desktop and I have not uploaded the nuget packages. I'll do it tomorrow. (I run a company and another FLOSs project and I've gotten a lot of PRs to review, so I'm a bit behind. ) |
Great thanks for the response @jzabroski ! Let me know if there's anything I can do to help. Our current lib is .Net framework only. Razor templates are a critical part of our update to .Net core - without a working solution the whole upgrade project is a no-go. :( |
@jbaumbach If you run into issues with using it in .NET Framework, just provide me with a repro. If you're not familiar with Git, just download Github Desktop and fork toddams/RazorLight from within GitHub Desktop. In the latest version of GitHub Desktop, forking it from within GitHub desktop correctly sets up the remote origin and upstreams for you, but be careful not to dismiss the dialogs. I agree, I have plenty of customers still on .NET Framework and so I would like to keep RazorLight a .NET Framework project as long as possible. Happy to compare notes on how to plan an upgrade via email. |
@knuxbbs I fixed strange xmldocs issues so that should be some progress towards this task of "Improve documentation". |
Is your feature request related to a problem? Please describe.
As pointed in #396 , there is very little guidance to an user who wants to use your Razor views and pages as templates to another purposes.
Describe the solution you'd like
First of all, seems like this library doesn't work with pre-compiled views (#35), which is the default output for ASP.NET Core applications. This should be highlighted in the repository's README, as well as the need to set your views as EmbeddedResources.
Second, the guidance about using RazorLightEngine as a injected service should be in main page, not in an outdated wiki page. This, in fact, should be the standard way to use the library, and should be further encouraged.
The text was updated successfully, but these errors were encountered: