Mise à niveau de votre code à partir du modèle objet côté client SharePoint (CSOM) vers les bibliothèques PnP

Dans la solution classique SharePoint, vous avez probablement utilisé le modèle objet côté client (CSOM) pour .NET Framework comme bibliothèque cliente principale pour la consommation de données SharePoint. CSOM est disponible depuis de nombreuses années avec des versions différentes ciblant différentes versions de SharePoint en local et SharePoint Online. Depuis 2021, Microsoft a publié une nouvelle version de CSOM pour SharePoint Online qui cible .NET Standard 2.0 et qui, à ce titre, peut être référencée dans .NET Framework 4.5+, .NET Core 2.0+ et .NET 5.0/6.0/7.0/8.0.

Importante

Cet article fait référence aux composants, exemples et/ou outils PnP qui sont des ressources open source soutenues par une communauté active qui les prend en charge. Il n’existe aucun contrat de niveau de service pour la prise en charge des outils open source des canaux de support Microsoft officiels. Toutefois, ces composants ou exemples utilisent des API et des fonctionnalités prêtes à l’emploi prises en charge par Microsoft.

Si vous préférez, vous pouvez regarder la vidéo suivante, au lieu de lire l’article entier, que vous pouvez toujours considérer comme une référence beaucoup plus détaillée.

Pour utiliser CSOM, vous devez simplement référencer le package NuGet Microsoft.SharePointOnline.CSOM , créer un objet ClientContext , configurer l’authentification et commencer à consommer les données SharePoint Online. Pour l’authentification, dans CSOM, il existait auparavant la prise en charge du type SharePointOnlineCredentials afin de tirer parti de l’authentification par nom d’utilisateur et mot de passe avec SharePoint Online. Toutefois, depuis que Microsoft est passé à l’authentification moderne, l’authentification par nom d’utilisateur et mot de passe n’est plus prise en charge, et vous devez vous appuyer sur OAuth et l’authentification moderne. Dans l’extrait de code suivant, vous pouvez voir un exemple d’utilisation du modèle CSOM simple avec l’authentification moderne via la bibliothèque d’authentification Microsoft (MSAL).

using Microsoft.SharePoint.Client;
using Microsoft.Identity.Client;

var clientId = "<client-Id>";
var tenantId = "<tenant-Id>";
var authority = $"https://login.microsoftonline.com/{tenantId}/";
var redirectUri = "http://localhost";

var siteUrl = new Uri("https://contoso.sharepoint.com/sites/TargetSite");

var accessToken = await AcquireTokenAsync(siteUrl);

using (var context = new ClientContext(siteUrl))
{
    context.ExecutingWebRequest += async (sender, e) =>
    {
        // Insert the access token in the request
        e.WebRequestExecutor.RequestHeaders["Authorization"] = "Bearer " + accessToken;
    };

    // Read web properties
    var web = context.Web;
    context.Load(web, w => w.Id, w => w.Title);
    await context.ExecuteQueryAsync();

    Console.WriteLine($"{web.Id} - {web.Title}");

    // Retrieve a list by title together with selected properties
    var documents = web.Lists.GetByTitle("Documents");
    context.Load(documents, d => d.Id, d => d.Title);
    await context.ExecuteQueryAsync();

    Console.WriteLine($"{documents.Id} - {documents.Title}");

    // Retrieve the top 10 items from the list
    var query = CamlQuery.CreateAllItemsQuery(10);
    var items = documents.GetItems(query);
    context.Load(items);
    await context.ExecuteQueryAsync();

    // Browse through all the items
    foreach (var i in items)
    {
        Console.WriteLine($"{i.Id} - {i["Title"]}");
    }     
}

La méthode AcquireTokenAsync s’appuie sur MSAL pour récupérer un jeton d’accès via l’authentification interactive. L’implémentation de la méthode n’est pas fondamentale dans ce contexte, mais vous la trouverez dans l’exemple sur le modèle CSOM associé à cet article.

Dans les sections à venir, vous verrez comment améliorer la qualité, la lisibilité et la maintenabilité de votre code à l’aide de bibliothèques .NET modernes telles que PnP Framework et le Kit de développement logiciel (SDK) PnP Core.

Présentation de la bibliothèque Du framework PnP

La bibliothèque PnP Framework (publiée en tant que v. 1.0 en janvier 2021) est l’évolution de CSOM et d’une ancienne bibliothèque appelée PnP Sites Core (désormais mise hors service et archivée). La bibliothèque PnP Framework cible .NET Standard 2.0 et .NET 5.0/6.0/7.0. Vous pouvez donc l’utiliser sur n’importe quelle plateforme (Windows, Linux, MacOS) et dans n’importe quel service cloud comme Azure App Services, Azure Functions, Conteneurs, etc.

Par défaut, cette bibliothèque prend uniquement en charge SharePoint Online (SPO). Si vous développez une solution moderne pour SharePoint Online à l’aide de .NET et que vous souhaitez avoir un style de codage de type CSOM, vous devez certainement installer le package NuGet PnP.Framework et l’utiliser.

D’un point de vue fonctionnel, l’infrastructure PnP est un ensemble d’extensions basées sur CSOM, multiplateforme et utilise le nouveau modèle objet côté client (CSOM) de SPO pour .NET Standard. Il cible principalement l’authentification moderne avec OAuth 2.0, mais il existe toujours une prise en charge du mode application uniquement dans ACS pour les applications « déjà existantes ».

Par défaut, la bibliothèque PnP Framework utilise une application Azure Active Directory multilocataire appelée PnP Management Shell, que vous devez inscrire dans votre locataire à l’aide de la syntaxe PowerShell PnP suivante.

Register-PnPManagementShellAccess

Cela lance un flux de connexion qui vous demande de donner votre consentement à l’application. Notez que n’est requis qu’une seule fois par locataire. Vous devez disposer des droits d’accès appropriés pour pouvoir donner votre consentement aux applications dans votre azure AD.

Toutefois, dans cet article, vous allez vous appuyer sur l’authentification moderne avec une application AAD personnalisée que vous devez inscrire et configurer pour l’authentification de bureau avec http://localhost comme URI de redirection pris en charge.

Importante

Pour en savoir plus sur l’utilisation de l’authentification moderne et d’AAD au lieu d’ACS, vous pouvez lire l’article Mise à niveau d’applications SharePoint à partir d’Azure Access Control Service vers Azure Active Directory.

À présent, nous allons créer une application console .NET pour consommer des données SharePoint Online à l’aide de la bibliothèque PnP Framework. Tout d’abord, vous devez ajouter une référence au package nuget PnP.Framework . Dans Visual Studio, vous pouvez simplement ajouter une référence de package à l’aide de l’interface utilisateur. Dans Visual Studio Code, vous devez exécuter la commande suivante.

dotnet add package PnP.Framework

Une fois cela fait, votre projet fait référence non seulement à la bibliothèque Du framework PnP, mais également à la bibliothèque CSOM, qui est utilisée en interne par PnP Framework. Dans l’exemple de code suivant, vous pouvez voir comment utiliser l’infrastructure PnP pour vous connecter à SPO et consommer des données, à l’aide d’une instance de la classe AuthenticationManager et de l’authentification moderne avec OAuth 2.0.

using Microsoft.SharePoint.Client;
using PnP.Framework;

var clientId = "<client-Id>";
var tenantId = "<tenant-Id>";
var redirectUrl = "<redirect-Url>";
var siteUrl = "<target-Site-Url>";

// Create an instance of the AuthenticationManager type
var authManager = AuthenticationManager.CreateWithInteractiveLogin(clientId, redirectUrl, tenantId);

// Get a reference to the ClientContext of CSOM
using (var context = await authManager.GetContextAsync(siteUrl))
{
    // Read web properties
    var web = context.Web;
    context.Load(web, w => w.Id, w => w.Title);
    await context.ExecuteQueryRetryAsync();

    Console.WriteLine($"{web.Id} - {web.Title}");

    // Retrieve a list by title together with selected properties
    var documents = web.GetListByTitle("Documents", l => l.Id, l => l.Title);

    Console.WriteLine($"{documents.Id} - {documents.Title}");

    // Retrieve the top 10 items from the list
    var query = CamlQuery.CreateAllItemsQuery(10);
    var items = documents.GetItems(query);
    context.Load(items);
    await context.ExecuteQueryRetryAsync();

    // Browse through all the items
    foreach (var i in items)
    {
        Console.WriteLine($"{i.Id} - {i["Title"]}");
    }     
}

Le code ci-dessus s’appuie sur une connexion web et interactive pour accéder à un site SharePoint Online cible. L’authentification est gérée par la classe AuthenticationManager de PnP Framework, ce qui vous offre une technique simple et simplifiée pour vous authentifier auprès de SharePoint Online à l’aide de l’une des options suivantes :

• Authentification utilisateur interactive
• Nom d’utilisateur et mot de passe (où le mot de passe doit être stocké dans une SecureString)
• Code d’appareil avec une application inscrite dans Azure Active Directory
• Flux de code d’autorisation
• ID client et clé secrète client pour l’authentification d’application uniquement
• Certificat X.509 pour l’authentification d’application uniquement
• Flux on-behalf-of
• Azure ACS pour l’authentification d’application uniquement

L’exemple de code contient id et titre d’une bibliothèque avec le titre « Documents » et récupère les 10 premiers éléments de la bibliothèque, afin d’afficher l’ID et le titre de ces éléments. La syntaxe est très proche de ce que vous avez l’habitude d’utiliser dans CSOM. En fait, vous obtenez un objet de contexte , qui est de type Microsoft.SharePoint.Client.ClientContext à partir de CSOM, et vous l’utilisez. Toutefois, par exemple, vous utilisez la méthode ExecuteQueryRetryAsync , qui est en fait une méthode d’extension .NET fournie par PnP Framework, ou vous utilisez la méthode GetListByTitle , qui est une autre méthode d’extension fournie par PnP Framework. De plus, dans PnP Framework, il existe de nombreuses méthodes asynchrones qui vous permettent d’écrire du code asynchrone moderne.

Dans la bibliothèque PnP Framework, il existe des milliers de méthodes d’extensions pour les types CSOM afin d’améliorer la qualité, la lisibilité et l’efficacité du code. De plus, dans l’infrastructure PnP, il y a également l’implémentation du moteur d’approvisionnement PnP, qui est le moteur utilisé par de nombreuses entreprises et par Microsoft lui-même pour automatiser l’approvisionnement des sites et des artefacts.

Enfin, l’infrastructure PnP se trouve dans le back-end de la plupart des applets de commande fournies par le module PowerShell PnP et fournit l’infrastructure de base pour le moteur de transformation de page PnP de l’infrastructure de modernisation PnP.

En règle générale, pnP Framework est la bibliothèque « de facto » que chaque développeur SharePoint doit utiliser pour créer des solutions modernes pour SPO dans Microsoft .NET.

Présentation de la bibliothèque du Kit de développement logiciel (SDK) PnP Core

Le Kit de développement logiciel (SDK) PnP Core est une nouvelle bibliothèque introduite par la communauté PnP Microsoft 365 pour le développement cloud moderne. Il a été mis en ligne début février 2021 et cible .NET Standard 2.0 et .NET 5.0/6.0/7.0. Par conséquent, vous pouvez l’utiliser sur n’importe quelle plateforme (Windows, Linux, MacOS) et dans n’importe quel service cloud, et est disponible en tant que package NuGet nommé PnP.Core.

La bibliothèque du Kit de développement logiciel (SDK) PnP Core a été conçue pour le développement moderne. En fait, il prend en charge en mode natif l’injection de dépendances (DI), une architecture orientée service, une syntaxe Fluent incluant la prise en charge de LINQ (Language Integrated Query) et un modèle de développement asynchrone. Il prend également en charge en mode natif le traitement par lot des demandes au niveau REST et la logique de nouvelle tentative automatique en cas de limitation des requêtes.

Vous vous demandez peut-être quelle est la différence entre Le Framework PnP et le Kit de développement logiciel (SDK) PnP Core. En fait, le Kit de développement logiciel (SDK) PnP Core est utilisé par l’infrastructure PnP et il a été implémenté avec un état d’esprit indépendant du modèle CSOM de SharePoint. En fait, de plus en plus de nouvelles fonctionnalités introduites dans SPO ne sont pas nécessairement disponibles via CSOM. C’est la raison pour laquelle pnP Core SDK a été introduit et il est sous le couvert de PnP Framework et PnP PowerShell, pour certaines fonctionnalités.

Le Kit de développement logiciel (SDK) PnP Core est souvent appelé bibliothèque PnP Graph First, car l’objectif de cette bibliothèque est d’aider les développeurs .NET modernes qui utilisent SPO et Microsoft Teams (Teams) via Microsoft Graph. En fait, Microsoft Graph est l’API standard pour l’utilisation des charges de travail Microsoft 365, y compris SPO et Teams. Toutefois, au moment de la rédaction de cet article, certaines fonctionnalités ne sont pas encore disponibles ou ne sont pas encore entièrement disponibles via Microsoft Graph, comme par exemple la prise en charge complète des pages modernes, ou qui nécessitent des améliorations afin d’être entièrement comparables à ce qui est proposé par l’API REST de SPO.

Avec le Kit de développement logiciel (SDK) PnP Core, vous disposez d’une couche d’abstraction au-dessus des API principales, ce qui vous permet de vous concentrer sur votre objectif métier : créer des solutions modernes sur SPO et Teams. En couverture, le Kit de développement logiciel (SDK) PnP Core cible Microsoft Graph si la fonctionnalité que vous recherchez est disponible via Graph, ou si elle revient à l’API REST de SPO quand elle est nécessaire.

Microsoft Graph se développe et évolue rapidement, et les développeurs n’ont pas besoin de mettre à jour leur code en permanence en utilisant cette technique. Ils peuvent simplement s’appuyer sur le Kit de développement logiciel (SDK) PnP Core, qui fera le bon choix pour eux. Si une fonctionnalité est manquante aujourd’hui dans Microsoft Graph, lorsqu’elle sera ajoutée, les développeurs devront simplement mettre à jour le package NuGet du Kit de développement logiciel (SDK) PnP Core, sans avoir à modifier une ligne de leur code.

Le Kit de développement logiciel (SDK) PnP Core cible uniquement les charges de travail cloud (SPO et Teams), et du point de vue de l’authentification, il s’appuie sur un modèle ouvert basé sur OAuth 2.0. Fondamentalement, vous pouvez implémenter la couche d’authentification avec la technique de votre choix, à condition de fournir un jeton d’accès valide. Si vous souhaitez utiliser la bibliothèque d’authentification Microsoft (MSAL), il existe un package dédié, appelé PnP.Core.Auth, que vous pouvez plug-in et utiliser pour authentifier l’accès aux services cloud cibles via MSAL.

Pour utiliser le nouveau Kit de développement logiciel (SDK) PnP Core, vous devez simplement créer un projet .NET, ajouter une référence au package NuGet nommé PnP.Core.Auth, qui inclut une dépendance sur le package PnP.Core principal, et vous pouvez commencer à l’utiliser.

Pour créer un exemple, nous allons créer une application console .NET, qui s’appuie sur l’injection de dépendances via le package NuGet Microsoft.Extensions.Hosting , pour consommer des données SharePoint Online à l’aide de la bibliothèque du SDK PnP Core. Pour ajouter une référence à PnP.Core.Auth, dans Visual Studio, vous pouvez simplement ajouter la référence de package à l’aide de l’interface utilisateur. Dans Visual Studio Code, vous devez exécuter la commande suivante.

dotnet add package PnP.Core.Auth
dotnet add package Microsoft.Extensions.Hosting

Vous êtes maintenant prêt à définir l’hôte de service et à générer la chaîne de services, y compris ceux fournis par le Kit de développement logiciel (SDK) PnP Core.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using PnP.Core.Auth.Services.Builder.Configuration;
using PnP.Core.Services.Builder.Configuration;
using PnP.Core.Services;
using PnP.Core.QueryModel;

var host = Host.CreateDefaultBuilder()
// Configure services with Dependency Injection
.ConfigureServices((hostingContext, services) =>
{
    // Add the PnP Core SDK library services
    services.AddPnPCore();
    // Add the PnP Core SDK library services configuration from the appsettings.json file
    services.Configure<PnPCoreOptions>(hostingContext
        .Configuration.GetSection("PnPCore"));
    // Add the PnP Core SDK Authentication Providers
    services.AddPnPCoreAuthentication();
    // Add the PnP Core SDK Authentication Providers 
    // configuration from the appsettings.json file
    services.Configure<PnPCoreAuthenticationOptions>(hostingContext
        .Configuration.GetSection("PnPCore"));
})
// Let the builder know we're running in a console
.UseConsoleLifetime()
// Add services to the container
.Build();

// Start console host
await host.StartAsync();

// Optionally create a DI scope
using (var scope = host.Services.CreateScope())
{
    // Obtain a PnP Context factory
    var pnpContextFactory = scope.ServiceProvider
        .GetRequiredService<IPnPContextFactory>();
    // Use the PnP Context factory to get a PnPContext for the given configuration
    using (var context = await pnpContextFactory.CreateAsync("SiteToWorkWith"))
    {
        // Retrieving web with lists and masterpageurl loaded ==> SharePoint REST query
        var web = await context.Web.GetAsync(p => p.Title, p => p.Lists,
        p => p.MasterUrl);

        // Output some information about the web
        Console.WriteLine($"{web.Id} - {web.Title}");

        // Browse through the requested lists
        foreach (var l in web.Lists.AsRequested())
        {
            Console.WriteLine($"{l.Id} - {l.Title}");
        }
    }
}

// Cleanup console host
host.Dispose();

Dans l’extrait de code, vous pouvez remarquer que le Kit de développement logiciel (SDK) PnP Core fournit son propre objet de contexte, appelé PnPContext, que vous pouvez utiliser pour accéder à SPO ou Teams à l’aide d’un modèle de domaine dédié de types, qui est entièrement indépendant de CSOM ou De Microsoft Graph, et qui fournit la couche d’abstraction nécessaire pour dissocier le SDK PnP Core des services REST principaux. Vous pouvez également remarquer la syntaxe Fluent, où vous pouvez accéder à la propriété Web de l’instance PnPContext et appeler des méthodes sur celle-ci, sans avoir à charger d’abord l’instance d’objet web.

Pour pouvoir exécuter un exemple comme celui que vous venez de voir, vous devez fournir un fichier de configuration (appsettings.json) comme celui que vous voyez dans l’extrait de code suivant.

{
    "PnPCore": {
        "Credentials": {
        "DefaultConfiguration": "interactive",
        "Configurations": {
            "interactive": {
                "Interactive": {
                    "RedirectUri": "http://localhost"
                }
            }
        }
        },
        "Sites": {
            "SiteToWorkWith": {
                "SiteUrl": "https://consoto.sharepoint.com/sites/targetSite"
            }
        }
    }
}

Si vous le souhaitez, vous pouvez également fournir les paramètres de configuration simplement à l’aide de code, sans vous appuyer sur un fichier de configuration .json.

Importante

Vous trouverez plus d’informations sur l’utilisation du nouveau Kit de développement logiciel (SDK) PnP Core dans la documentation officielle qui lit le document Kit de développement logiciel (SDK) PnP Core.

Quelle que soit la technique que vous allez utiliser pour créer une instance configurée du type PnPContext , une fois que vous l’avez, vous pouvez facilement accéder au site SPO lié au contexte. Si le site est un site d’équipe moderne, vous pouvez également accéder à l’équipe dans Microsoft Teams qui est connectée au site d’équipe, comme dans l’extrait de code suivant.

// Get a reference to the team connected to the current site, including the FunSettings
var team = await context.Team.GetAsync(t => t.FunSettings);

// Show one of the settings in the FunSettings property
Console.WriteLine($"Are Giphy allowed? {team.FunSettings.AllowGiphy}");

Une autre fonctionnalité intéressante du Kit de développement logiciel (SDK) PnP Core est la prise en charge des requêtes LINQ (Language Integrated Query), afin que vous puissiez interroger le modèle objet du Kit de développement logiciel (SDK) PnP Core à l’aide de LINQ. Par exemple, dans l’extrait de code suivant, vous pouvez voir comment interroger les listes de l’objet web actuel filtré par TemplateType, afin que nous puissions récupérer uniquement les bibliothèques de documents.

// Define a LINQ query to retrieve only the document libraries of the current web
var lists = (from l in context.Web.Lists
            where l.TemplateType == PnP.Core.Model.SharePoint.ListTemplateType.DocumentLibrary
            select l);

Console.WriteLine("=> Here are all the document libraries:");

// Browse the lists resulting from the LINQ query
foreach (var l in lists)
{
    Console.WriteLine($"{l.Id} - {l.Title} - {l.TemplateType}");
}

Combinaison de l’utilisation de PnP Framework et du Kit de développement logiciel (SDK) PnP Core

Après avoir lu cet article, vous vous demandez peut-être ce que vous devez utiliser et quand.

Si vous êtes un développeur SharePoint, que vous avez l’habitude de travailler avec CSOM, ou si vous avez déjà un projet existant basé sur Les sites PnP Core et CSOM, vous devez vous appuyer sur PnP Framework et commencer à créer des solutions modernes en tirant parti de l’ensemble complet d’extensions et d’utilitaires fournis par la nouvelle bibliothèque PnP Framework.

Si vous êtes développeur .NET, prêt à créer une nouvelle solution moderne pour SPO, commencez à travailler avec le KIT DE développement logiciel (SDK) PnP Core et profitez de l’utilisation de Microsoft Graph et des API REST SPO avec une couche d’abstraction de haut niveau.

Si vous le souhaitez, vous pouvez même utiliser les deux bibliothèques, en fonction de ce que vous devez faire. Par exemple, si vous devez effectuer un approvisionnement automatisé de sites à l’aide du moteur d’approvisionnement PnP, vous devez nécessairement vous appuyer sur PnP Framework. Si vous avez besoin d’interroger des objets SharePoint à l’aide de LINQ, vous devez nécessairement vous appuyer sur le Kit de développement logiciel (SDK) PnP Core. Et vous pouvez utiliser et basculer le contexte de l’un vers l’autre. Par exemple, dans l’extrait de code suivant, vous pouvez voir comment passer de PnP Framework à PnP Core SDK, en partageant le même contexte.

// Create an instance of the AuthenticationManager type
var authManager = AuthenticationManager.CreateWithInteractiveLogin(clientId, redirectUrl, tenantId);

// Get a reference to the ClientContext of CSOM
using (var csomContext = await authManager.GetContextAsync(siteUrl))
{
    // Use CSOM to load the web title
    csomContext.Load(csomContext.Web, p => p.Title);
    csomContext.ExecuteQueryRetry();
    Console.WriteLine($"Title from PnP Framework: {csomContext.Web.Title}");

    using (PnPContext pnpCoreContext = PnPCoreSdk.Instance.GetPnPContext(csomContext))
    {
        // Use PnP Core SDK (Microsoft Graph / SPO Rest) to load the web title
        var web = await pnpCoreContext.Web.GetAsync(p => p.Title);

        Console.WriteLine($"Title from PnP Core SDK: {web.Title}");
    }
}

Dans l’extrait de code suivant, vous pouvez voir comment passer du Kit de développement logiciel (SDK) PnP Core à PnP Framework, en partageant le même contexte.

using (var scope = host.Services.CreateScope())
{
    // Obtain a PnP Context factory
    var pnpContextFactory = scope.ServiceProvider
        .GetRequiredService<IPnPContextFactory>();
    // Use the PnP Context factory to get a PnPContext for the given configuration
    using (var pnpCoreContext = await pnpContextFactory.CreateAsync("SiteToWorkWith"))
    {
        // Use PnP Core SDK (Microsoft Graph / SPO Rest) to load the web title
        var web = await pnpCoreContext.Web.GetAsync(p => p.Title);
        Console.WriteLine($"Title from PnP Core SDK: {web.Title}");

        using (ClientContext csomContext = PnPCoreSdk.Instance.GetClientContext(pnpCoreContext))
        {
            // Use CSOM to load the web title
            csomContext.Load(csomContext.Web, p => p.Title);
            csomContext.ExecuteQueryRetry();

            Console.WriteLine($"Title from PnP Framework: {csomContext.Web.Title}");
        }   
    }
}

Par conséquent, vous pouvez librement parcourir les deux bibliothèques et profiter de la nouvelle expérience de codage.

Contenu recommandé

Vous trouverez des informations supplémentaires sur cette rubrique en lisant les documents suivants :

• Utilisation de CSOM pour .NET Standard au lieu de CSOM pour .NET Framework
• PnP Framework
• Kit de développement logiciel (SDK) PnP Core
• Demande de données à partir de Microsoft 365
• Utilisation de la pagination
• Interopérabilité avec PnP Framework
• PowerShell PnP
• Moteur d’approvisionnement PnP
• PnP Page Transformation