Universe.NetCore.Sp.CSOM.CQRS 1.0.0.100

Description of the Universe.NetCore.Sp.CSOM

Universe.NetCore.Sp.CSOM.Common - a base package for a Client SharePoint Object Model. Universe.NetCore.Sp.CSOM.CQRS - contains the more modern base implementation of CQRS for CSOM SharePoint (The Command and Query Responsibility Segregation). The part of Universe.Framework.

All projects here relates CSOM and SharePoint Online in a separate way and a separate package, because it's basing on a complex of assemblies, which relates with Microsoft.SharePoint.Client at first and at second objects there without SP prefixes like FieldLookupValue insted SPFieldLookupValue, CamlQuery instead SpQuery and has a different behavior then SSOM. Here modern version of this project

CamlQuery - similar with CamlHelper for SSOM is a builder of CamlQueries.

Consists usually tree construction: where, order, viewFields like the server mode and example of using same. Excluded interaction with taxonomy fields, they're supporting only in SSOM.

ListItemHelper - helper for «ListItem». Helps to get typed value from item of List: GetBool, GetDouble, GetInt32, GetDateTime, GetMultiChoiceValue, GetLookup, GetUserValue. When you're using one of query in Universe.Sp.CSOM.CQRS, this helper is using automatically for mapping values to Spo. If you want to create own custom query, just use it as extensions to «ListItem».

FieldLookupValue string representation similar in SSOM: 2021;#Epica - Omega, where 2021 - ID of item in the lookup table; ;# - separator Epica - Omega - title from lookup table

SpQueryExt - set of extensions that, builds object of CamlQuery for request in CSOM more a simple way. Example of using:

 var camlQuery = SpQueryExt.ItemsQuery(
   where: CamlHelper.GetCamlWhere(
      CamlHelper.CamlChain(
        CamlHelper.LogicalOperators.OR,
        CamlHelper.CamlChain(
          CamlHelper.LogicalOperators.AND,
          CamlHelper.GetEqText(
           "Name",
           "Epica - Code Of Life")
       ))),
   viewFields: CamlHelper.BuildFieldsRef(
      "ID",
      "Title",
      "Name"),
   rowLimit: 2000
 );

Version control

For convenience, the project should be cloned to the local path C:\P\Universe.Lastfm.API\ (but this is not at all necessary)

• master is the main working branch, changes are made to it only through MergeRequests
• develop - the second main working branch, changes are also included in it through MergeRequests

A separate branch is created for each development/bug fix task.

It is created directly from the task, it is necessary to include errors in the name of the task; before creating it, indicate in parentheses in English the not very long name of the branch.

Rules for generating messages to a commit

The message also can be multi-line, for example: #89 [WebApp Auth]: Added authorization in the web application. #89 [Common]: Changed links to projects. #89 [Universe.Algorithm, Tests]: Removed artifact.

where:

• #89 - issue number (usually the same as the branch number) - in gitlab it will turn into a link to the issue, and when you hover the mouse it will show the name of the task

• "[WebApp Auth]:"" name of the functionality within which the commit is made. Must be indicated with a colon at the end.

• "Authorization has been added to the web application." - text describing what was done. Be sure to have a period at the end to complete the sentence.

• Several actions can be listed that are recorded in this manner e.g. "#89 WebApp Auth: The Unity container is connected in the WebApp project. The Unity container is connected in the Core project.""

• [~] - we indicate it at the beginning of the commit line if we are merging files manually (git automatically generates a message). The message should look like: [~] Merge from develop to 20-build-ef-data-access-layer or [~] Merge from develop to #20

Development tools

For a development, you should use VS 2017, VS2019, VS2022; also must additionally be installed:

• support for PowerShell projects (this is installed when installing VS)
• git integrated into studio (this is installed when installing VS)
• If, after updating from the develop branch, the projects' References are gone, and the error shows "NuGet", you can do the following: on Solution, right-click and select and select Restore NuGet Packages. Then Clean solution, build solution.
• To have NuGet restore assemblies automatically, you need to do the following: in the Tools - Options - NuGet Package Manager menu, select 2 checkboxes:
  • Allow NuGet to download missing packages;
  • Automaticall check for missing packages during build in Visual Studio.

Note

• File encoding (especially *.ps1) must be UTF-8

CodingStyle

• When formatting the code, follow the resharper settings in the ReSharper.DotSettings file
• !Before committing, be sure to reformat the changed code according to the ResharperSln scheme (exceptions are codogen and code generated by T4 template)
• When reformating, select the ResharperSln profile for a full reformat, ResharperSln NoSort for classes in which the order cannot be changed
• Catch block, if there is no throw ...; in the catch block, then you need to indicate a comment why it is not there, for example as in the example below If a new error instance is created in the catch block, then it is necessary to indicate the original error or comment why the original error should not be stated.

catch (Exception ex) {
    _log.Unexpected(ex);
    //throw; Whatever happens here should not affect the execution of everything else
}

Examples of using ...

Creating of sets using of concrete conditions:

var accessMatrixMi = MetaInfo.UniverseWeb.AccessMatrixList;
var accessMatrixList = Web.GetSpListByUrl(accessMatrixMi.WebRelativeUrl);
var field = accessMatrixList.Fields.GetField(fieldInternalNameArgument) as SPFieldMultiChoice;
if (field == null)
{
    return false;
}

var items = accessMatrixList.GetItemsByQuery(
        where: CamlHelper.GetCamlWhere(
            CamlHelper.CamlChain(
                CamlHelper.LogicalOperators.AND,
                CamlHelper.GetEqLookup(accessMatrixMi.UvUser.InternalName, Web.CurrentUser.ID))),
        order: CamlHelper.GetCamlOrderBy(CamlHelper.GetCamlOrderByElement(accessMatrixMi.ID.InternalName, true)),
        viewFields: CamlHelper.BuildFieldsRef(
            field.InternalName))
    .Select(x => new
                {
                    Roles = x.GetMultiChoiceValue(field.InternalName)
                }).ToList();

var req = new GetSpEntitiesReq
{
    FieldMapContainer = new FieldMapContainer<DepartureApplicationSp>
    {
        FieldMap = new Dictionary<string, Expression<Func<DepartureApplicationSp, object>>>
        {
            { "Title", x => x.Title }
        }
    },
    SpQuery = SpQueryExt.ItemsQuery(
        where: CamlHelper.GetCamlWhere(
            CamlHelper.CamlChain(
                CamlHelper.LogicalOperators.OR,
                CamlHelper.CamlChain(
                    CamlHelper.LogicalOperators.AND,
                    CamlHelper.GetEqText(
                        nameof(ResearchesSp.Title),
                        "Universe.NetCore.SharePoint.CSOM.CQRS")
                ))),
        viewFields: CamlHelper.BuildFieldsRef(
            "ID",
            "Title",
            "Name",
            nameof(ResearchesSp.PackageDescription),
            nameof(ResearchesSp.AdditionalInformation)),
        rowLimit: 2000
    )
};

var result = scope.GetQuery<GetSpEntitiesQuery<ResearchesSp>>().Execute(
    req
);

SharePoint API Authorization

This is a C# assemblies that interacts with SharePoint Online using the SharePoint REST API. Assemblies uses an Azure AD App Registration with application permissions and certificate-based authentication to perform various operations like retrieving site details, creating lists, and fetching list items.

Features

• Retrieve SharePoint site information.
• Execute custom SharePoint REST API calls.
• Create new SharePoint lists.
• Retrieve all items from a specific SharePoint list.

Prerequisites

Azure App Registration:

• Create an app registration in Azure Active Directory.
• Assign Application Permissions for SharePoint:
  • Sites.FullControl.All or Sites.Manage.All.
• Upload a certificate (used for authentication).
• Grant admin consent to the app.

Certificate Setup:

• Generate a certificate using a tool like OpenSSL or PowerShell.
• Install the certificate in the Windows Certificate Store under CurrentUser → Personal.
• Note the certificate thumbprint for use in the application.

Environment:

• .NET 8.0 or later installed.
• Access to a SharePoint Online site.

Installation:

1. Clone the repository
2. Install dependencies: Ensure you have the required .NET libraries, such as Microsoft.Identity.Client
3. Open the project in Visual Studio or your preferred IDE
4. Update Program.cs with your Azure App Registration details:
   • tenantId: Your Azure AD tenant ID
   • clientId: Your app registration's client ID
   • certificateThumbprint: The thumbprint of your uploaded certificate
   • sharepointSiteUrl: The URL of your SharePoint site
5. Build and run the application:
   • dotnet build
   • dotnet run

Cert creation

Generate a private key

openssl genrsa -out privatekey.pem 2048

Create a Certificate Signing Request (CSR)

openssl req -new -key privatekey.pem -out certrequest.csr

Create a self-signed certificate

openssl x509 -req -days 730 -in certrequest.csr -signkey privatekey.pem -out certificate.crt

Combine certificate and private key into a PFX file

openssl pkcs12 -export -out certificate.pfx -inkey privatekey.pem -in certificate.crt

Settings

Need to implement of interface ISpWebAppSettings and create your settings profile like AppTestSettings. This setting is using UniverseSpScope of Universe.NetCore.Sp.CSOM.CQRS. Don't forget to implement it!

    public class AppTestSettings: ISpWebAppSettings
    {
        public SharePointOnlineAuthParameters SharePointOnlineAuthParameters { get; set; }

        public AppTestSettings()
        {
            SharePointOnlineAuthParameters = new SharePointOnlineAuthParameters
            {
                WebUrl = $"https://<Your Tenant>.sharepoint.com/sites/UES-Support",

                SpTenant = "https://<Your Tenant>.sharepoint.com/",
                TenantId = "<Your Tenant ID>",
                ClientId = "<Your Client ID of Azure AD Application>",
                ClientSecret = "<Your Client Secret of Azure AD Application>",

                CertificatePath = $"{Directory.GetCurrentDirectory()}\\Certificates\\certificate.pfx"
            };
        }
    }

Also setup profiles DI-container using this UnityConfig:

    public static class UnityConfig
    {
        private static Lazy<IUnityContainer> container =
          new Lazy<IUnityContainer>(() =>
          {
              var container = new UnityContainer();
              RegisterTypes(container);
              return container;
          });

        /// <summary>
        /// Configured Unity Container.
        /// </summary>
        public static IUnityContainer Container => container.Value;

        /// <summary>
        /// Registers the type mappings with the Unity container.
        /// </summary>
        /// <param name="container">The unity container to configure.</param>
        /// <remarks>
        /// There is no need to register concrete types such as controllers or
        /// API controllers (unless you want to change the defaults), as Unity
        /// allows resolving a concrete type even if it was not previously
        /// registered.
        /// </remarks>
        public static void RegisterTypes(IUnityContainer container)
        {
            // NOTE: To load from web.config uncomment the line below.
            // Make sure to add a Unity.Configuration to the using statements.
            // container.LoadConfiguration();

            new UnityProfileApp(container).Apply();
        }
    }

and this profile for an application:

 public class UnityProfileApp
    {
        private readonly IUnityContainer _container;

        public UnityProfileApp(IUnityContainer container)
        {
            _container = container;
        }

        public virtual void Apply()
        {
            // Infrastructure
            _container.RegisterType<ISpWebAppSettings, AppTestSettings>(new HierarchicalLifetimeManager());
            _container.RegisterType<ISpWebAppPrincipalResolver, AppTestPrincipalResolver>(new SingletonLifetimeManager());
        }
    }