lombiq / helpful-libraries

Orchard Core library / Orchard 1.x module with libraries that can be handy when developing for Orchard.

Lombiq Helpful Libraries

About

Various useful libraries that can be handy when developing for .NET, ASP.NET Core, and Orchard Core, to be used from your own projects.

We at Lombiq also used this library for the following projects:

• The new City of Santa Monica website when migrating it from Orchard 1 to Orchard Core (see case study).
• The new Smithsonian Folkways Recordings website when migrating it from Orchard 1 to Orchard Core (see case study).
• The new Lombiq website when migrating it from Orchard 1 to Orchard Core (see case study).
• The new Ik wil een taart website (see case study).
• The new client portal for WTW (see case study).
• The new Git-hg Mirror website when migrating it from Orchard 1 to Orchard Core (see case study).
• The new Hastlayer website when migrating it from Orchard 1 to Orchard Core (see case study).

Do you want to quickly try out this project and see it in action? Check it out in our Open-Source Orchard Core Extensions full Orchard Core solution and also see our other useful Orchard Core-related open-source projects!

Note that this project has an Orchard 1 version in the dev-orchard-1 branch.

Documentation

Helpful Libraries consists of the following independent libraries (all in their own projects/packages). Use the one specific to your use-case, or most of them at once by depending on Lombiq.HelpfulLibraries.

• ASP.NET Core Libraries
• Command Line Libraries
• Common Libraries
• LINQ to DB Libraries for Orchard Core
• Orchard Core Libraries
• RestEase Libraries for Orchard Core (Not included in Lombiq.HelpfulLibraries, we suggest the Refit libraries instead.)
• Refit Libraries for Orchard Core

Public APIs are always documented so please always read method comments.

Check out the Lombiq.HelpfulLibraries.Samples project for various examples in the form of an Orchard Core module.

Note: The Lombiq.HelpfulLibraries.sln file exists to provide centralized building of the independent library projects but otherwise you don't need to use it.

Contributing and support

Bug reports, feature requests, comments, questions, code contributions and love letters are warmly welcome. You can send them to us via GitHub issues and pull requests. Please adhere to our open-source guidelines while doing so.

This project is developed by Lombiq Technologies. Commercial-grade support is available through Lombiq.

helpful-libraries's Issues

The existing field's DisplayName gets overwritten for no reason. (OSOE-474)

The ContentPartDefinitionBuilder<TPart>.WithField<TField>(...) extension method overwrites the DisplayName of an existing field.

Helpful-Libraries/Lombiq.HelpfulLibraries.OrchardCore/Contents/ContentPartDefinitionBuilderExtensions.cs

Lines 39 to 55 in 3c72f64

	public ContentPartDefinitionBuilder<TPart> WithField<TField>(
	Expression<Func<TPart, TField>> fieldPropertySelector,
	Action<ContentPartFieldDefinitionBuilder> configuration = null)
	{
	var property = ((MemberExpression)fieldPropertySelector.Body).Member;
	var name = property.Name;
	Builder = Builder.WithField(
	name,
	field =>
	{
	field = field.WithDisplayName(name).OfType(typeof(TField).Name);
	configuration?.Invoke(field);
	});
	return this;
	}

Expected behavior:
Keep the original DisplayName value if present.

Jira issue

The collection being enumerated is modified inside the `foreach` loop. (OSOE-605)

System.Collections.Generic.CollectionExtensions.RemoveAll(...) throws InvalidOperationException: 'Collection was modified; enumeration operation may not execute.'

Helpful-Libraries/Lombiq.HelpfulLibraries.Common/Extensions/CollectionExtensions.cs

Lines 26 to 39 in f62f1e0

	/// <summary>
	/// Removes every item <paramref name="collection"/> where <paramref name="predicate"/> returns <see
	/// langword="true"/> or if it's <see langword="null"/>.
	/// </summary>
	public static void RemoveAll<T>(this ICollection<T> collection, Func<T, bool> predicate = null)
	{
	foreach (var item in collection)
	{
	if (predicate == null || predicate(item))
	{
	collection.Remove(item);
	}
	}
	}

Exception:

Jira issue

Split the Orchard Core specific methods into its own project (OSOE-70)

We want to split up the main project and separate the .Net and Orchard Core extensions.

Create new projects:

• Lombiq.HelpfulLibraries.Common
• Lombiq.HelpfulLibraries.OrchardCore
• Also see if a third Lombiq.HelpfulLibraries.AspNetCore makes sense.

The OC module should contain the following package references to ensure the projects using them won't have issues with tag helpers and the like:

• OrchardCore.ContentManagement
• OrchardCore.DisplayManagement
• OrchardCore.ResourceManagement

Otherwise, remove all unnecessary package references. This might mean a switch to an *.Abstractions package instead of the implementation one.

The Lombiq.HelpfulLibraries project should remain and become an umbrella project that contains references to the others.

LinqQueryAsync throwing connection error if we setup Persist Security Info=False in connection string. (OSOE-801)

SQL login failed due to incorrect username and password, which was being thrown from the _session.LinqQueryAsync method. We investigated and discovered that the transaction.Connection.ConnectionString did not contain the password. As a workaround, we configured the Persist Security Info flag as true, which resolved the issue.

We received exceptions from Azure Application Insights, but no exceptions appeared on the local environment console.

Jira issue

Make it possible to replace content items with an unknown ID using recipes (OSOE-648)

Currently it's not possible to overwrite a content item with a recipe if its ContentItemId is unknown - for example if it was created from a recipe using "ContentItemId": "[js: uuid()]". We should include some recipe mechanism to get around this. Some ideas:

1. Add a IGlobalMethodProvider that let's you find the ContentItemId from alias, e.g.
   "ContentItemId": "[js: idFromAlias('main-menu')]".
2. Create a new recipe step that removes a content item by query.

I'm not sure if either of these is possible during setup, if the alias index may not be populated yet?

Jira issue

Retrive the Admin prefix from `AdminOptions.AdminUrlPrefix` instead of hardcoding it (OSOE-657)

Related comment: #208 (comment)

Here:
https://github.com/Lombiq/Helpful-Libraries/blob/dev/Lombiq.HelpfulLibraries.OrchardCore/Mvc/TypedRoute.cs#L96

Retrive the Admin prefix from AdminOptions.AdminUrlPrefix instead of hardcoding it.

Jira issue

Create `InvokeAsync` extension methods for `Task` returning delegates

When calling something like await delegate.Invoke() on a Task returning delegate there is a danger that it might be a multicast delegate. If so, actually only the final method will be awaited on the method's invocation list and the rest will be fire-and-forget.

If we introduce matching InvokeAsync methods, then AsyncFixer will emit a warning wherever the stock Invoke methods are called, preventing this dangerous practice. Such a method should call the methods on the invocation list in series, like here.

Ability to use LinqToDb with the non-default collection

Accessing tables from a custom collection is not supported currently (like this)

Are you planning to have the ability?

Add locking to CacheServiceMonitor

@Piedone created on Aug 12, 2015:
https://helpfullibraries.codeplex.com/workitem/7

The factory delegate in CacheServiceMonitor.GetKeys() can run multiple times on simultaneous requests, causing a stale keychain. It should instead use a distributed lock once its built into Orchard.

Enable nullable reference types in the solution and evaluate code (OSOE-754)

Enabling nullable mode for the HL would make the code much safer and give us more confidence about where additional null checks are needed or not. It's also painful to implement abstract methods from HL that should be able to return null in a nullable enabled project because the IDE gets confused.

Also the codebase should be reviewed to guarantee that the methods only return null when it has a special meaning (e.g. in drivers) and to consider making the inputs as resilient as possible.

Jira issue

Change the OC package references to 1.8.0 instead of 1.8.2 (OSOE-846)

Based on @Piedone 's advice in OCC:

I think the OCC packages should always target the .0 minor version of the latest version; i.e., 1.8.0 in this case, so people can use the packages regardless of them being on 1.8.0, 1.8.1, 1.8.2, or 1.8.3 (currently they're forced to use at least 1.8.2). During development and testing though, we should use the very latest, if somehow this can be done.

This is not possible for the projects that use HL, specifically OrchardCore.Commerce.Inventory and OrchardCore.Commerce.ContentFields.

Once this is done, also update OCC's Directory.Packages.props as suggested here.

Jira issue

Use source generation to create the `public partial class Program` needed by UITT (OSOE-829)

Now that we are dabbling in source generators, should we replace the boilerplate

[SuppressMessage(
    "Design",
    "CA1050: Declare types in namespaces",
    Justification = "As described here: https://docs.microsoft.com/en-us/aspnet/core/test/integration-tests?view=aspnetcore-6.0.")]
public partial class Program
{
    protected Program()
    {
        // Nothing to do here.
    }
}

with generated source too?

Jira issue

Updated for 1.10?

I downloaded the 1.10 branch for this module but I am getting a ton of build errors due to references not being correctly set, and I don't think it was updated to use Nuget?

Add missing docs to public methods and Markdown files (OSOE-153)

• Go through all the C# files and add docs to all public methods missing them.
• Go through all the Markdown docs and add notes on all missing classes that consumers directly interface with (i.e. not for every class, internal helpers or other types are not needed).

Jira issue

Does not work in Orchard 1.9.x

IMachineNameProvider got refactored into IApplicationEnvironment

OrchardCMS/Orchard#5813

Add source generator that reads a JSON value as a const string at compile time. (OSOE-819)

Disclaimer: I'm not sure if this is the right repo for this suggestion. I don't think we have done any source generators yet, so maybe it should be a new repo if we do this. The idea ties into node/npm but it's not dependent on Node Extensions.

Problem

When you include a vendor resource in OC, it's a good idea to include the version too, for the purpose of cache busting. For example

        _manifest
            .DefineScript(Library)
            .SetUrl(Vendors + "chart.js/Chart.min.js", Vendors + "chart.js/Chart.js")
            .SetVersion("2.9.4");

As you can see, the version here is just a raw string. It's derived from the matching "chart.js": "2.9.4", in package.json. Then later you update the package file and forget to update the matching version number in the resource manifest! It's a maintenance nightmare.

Solution

Create a source generator that creates a compile time constant. For instance:

[ConstantFromJson("ChartJsVersion", "package.json", "$..['chart.js']")]
public class ResourceManagementOptionsConfiguration : IConfigureOptions<ResourceManagementOptions>
{
    // ...
        _manifest
            .DefineScript(Library)
            .SetUrl(Vendors + "chart.js/Chart.min.js", Vendors + "chart.js/Chart.js")
            .SetVersion(ChartJsVersion);
    // ...
}

Here [ConstantFromJson(variableName, fileName, jsonPath)] would instruct the source generator to insert string constant called variableName and set its value to the first result in fileName that matches jsonPath. Then at compile time it will become private const ChartJsVersion = "2.9.4";. Of course, there should be a shortcut like [ValueFromNpm("chart.js")] as well.

I looked for existing projects, but this was the only thing vaguely similar.

Alternatives

You could mark the package.json an embedded file, then read & parse it rune time at every startup.
Just writing that sentence down made me feel ill.

Jira issue

Relative URL prefixed with /Admin in case of an admin controller action if [Route] attribute is used (OSOE-653)

The relative URL created by the TypedRoute.ToString() for a controller action where the controller has [Admin] attribute and the action has [Route] gets prefixed with /Admin. I think the expected result is the URL is not prefixed with /Admin.

Helpful-Libraries/Lombiq.HelpfulLibraries.OrchardCore/Mvc/TypedRoute.cs

Lines 92 to 101 in d5c11ae

	public override string ToString()
	{
	var prefix = _isAdminLazy.Value ? "/Admin/" : "/";
	var route = _routeLazy.Value;
	var arguments = _arguments.Any()
	? "?" + string.Join('&', _arguments.Select((key, value) => $"{key}={WebUtility.UrlEncode(value)}"))
	: string.Empty;
	return prefix + route + arguments;
	}

For the following example, the relative URL will be: /Admin/SampleModule/Admin/Edit

[Admin]
public class AdminController : Controller
{
    ...

    [Route("SampleModule/Edit")]
    public async Task<IActionResult> Edit(string contentItemId, string returnUrl)
    {
        ...
    }
}

Jira issue

Linq2db queries should only use transactions for write queries (OSOE-343)

As discussed at the Orchard meeting of 07.09.2021, for performance reasons linq2db queries shouldn't always open a transaction since for reads this is not necessary. Ideally, we'd have something like ITransactionManager.GetOrCreate() in Orchard or YesSql since YesSql opens transactions only the first time a write query happens, lazily.

See this discussion on what can be used from the linq2db API.

Jira issue