Conversion d’un complément auto-hébergé pour SharePoint en complément hébergé par un fournisseur
Microsoft SharePoint a introduit une nouvelle approche d'extension des sites SharePoint, en plus de l'approche précédente consistant à utiliser des personnalisations basées sur une solution. Ce nouveau modèle d'extensibilité pour SharePoint, appelé modèle de complément, permet aux développeurs de créer des implémentations personnalisées qui peuvent être déployées dans des environnements SharePoint, qu'ils soient en cours d'exécution dans un déploiement sur site, SharePoint Online ou hybride.
Les développeurs peuvent créer deux types de compléments SharePoint. Le premier type, un complément hébergé par SharePoint, est principalement exécuté dans le navigateur, et toutes les ressources qui le prennent en charge, telles que HTML, CSS, les images et JavaScript, sont stockées et desservies par SharePoint. Les autres types de compléments suivent le modèle de complément Cloud (CAM), s’exécutent principalement à l’extérieur de SharePoint sur un autre serveur et communiquent avec SharePoint au moyen du modèle CSOM (Client-side Server Object Model) et de l’API REST. Ils établissent une identité à l’aide du protocole populaire OAuth 2.0 pris en charge par SharePoint.
Les développeurs peuvent implémenter des compléments en utilisant le modèle de complément de deux manières différentes : en tant que complément hébergé par un fournisseur ou en tant que complément auto-hébergé. Les compléments auto-hébergés ont été publiés comme programme d’évaluation lors du lancement de SharePoint mais, en mai 2014, Microsoft a annoncé l’arrêt du programme d’évaluation et la fin de la prise en charge de la création de compléments auto-hébergés. Pour consulter l’annonce, consultez Mise à jour sur le programme d’évaluation des compléments auto-hébergés.
Cet article explique comment convertir et migrer un complément auto-hébergé en complément hébergé par un fournisseur. Cependant, il est important que les développeurs comprennent certaines différences spécifiques entre les deux approches, car ces informations simplifient grandement le processus de conversion.
Conditions préalables à la conversion d’un complément auto-hébergé en complément hébergé par un fournisseur
Concepts fondamentaux à connaître avant de convertir un complément auto-hébergé
Avant de convertir un complément auto-hébergé en complément hébergé par un fournisseur, vous devez comprendre les bases des compléments SharePoint et les différences entre les compléments SharePoint hébergés par SharePoint, hébergés par un fournisseur et auto-hébergés. Les articles répertoriés dans le tableau suivant devraient vous y aider.
| Titre d’article | Description |
|---|---|
| Compléments | Découvrez le nouveau modèle de complément de SharePoint qui permet de créer des compléments, c’est-à-dire de petites solutions simples d’utilisation pour les utilisateurs finaux. |
| Aspects importants du contexte de développement et de l'architecture des compléments pour SharePoint | Apprenez les différents aspects de l'architecture des Compléments SharePoint et du modèle de complément SharePoint, notamment les options d'hébergement des compléments, les options de l'interface utilisateur (IU), le système de déploiement, le système de sécurité et le cycle de vie. |
| Choisir les modèles de développement et l'hébergement d'un complément pour SharePoint | Découvrez les différentes méthodes d'hébergement pour les Compléments SharePoint. |
| Héberger des sites web, des sites web de complément et des composants SharePoint dans SharePoint | Découvrez la différence entre les sites web hôtes et les sites web de complément. Découvrez également les composants SharePoint qui peuvent être inclus dans un complément SharePoint, ceux qui sont déployés sur le site web hôte, ceux qui sont déployés sur le site web de complément, ainsi que le mode de déploiement du site web de complément dans un domaine isolé. |
Conversion du complément
La conversion d’un complément SharePoint auto-hébergé en complément hébergé par un fournisseur implique la modification de deux ou trois composants :
- Le complément SharePoint lui-même
- L'application ou les services web distants
- La base de données SQL Microsoft Azure, le cas échéant, dans le complément
Un complément SharePoint auto-hébergé déployé automatiquement sur le site web Azure et la base de données SQL Azure lors de son installation. Toutefois, l’application web à distance et d’autres services des compléments hébergés par un fournisseur peuvent exister sur n’importe quelle plateforme web. Cet article part du principe que les composants à distance d’un complément auto-hébergé sont conservés en tant que services Azure suite à la conversion en complément hébergé par un fournisseur.
Les sections suivantes présentent la procédure de conversion d’un complément auto-hébergé en un complément hébergé par un fournisseur. L’exemple de complément auto-hébergé utilisé, Customer Manager, est simple, de manière à mettre en évidence les étapes de conversion et non le complément par lui-même. Il est constitué de trois projets :
CustomersDb : projet de base de données SQL A qui génère le *.dacpac nécessaire. Notez qu’il n’y a pas de schéma défini dans ce projet. Il est simplement utilisé pour créer une base de données, car le schéma est créé par l’application web ASP.NET.
CustomerManagerAH : complément SharePoint auto-hébergé qui est configuré pour inclure le projet d’application web ASP.NET et l’application de la couche Données SQL Azure dans le package de complément SharePoint obtenu.
CustomerManagerAHWeb : application web MVC ASP.NET qui utilise l’approche Migrations Entity Framework Code First pour créer le schéma de base de données, ainsi que pour lire et écrire dans la base de données.
Le complément est une application web ASP.NET MVC qui peut à la fois afficher les clients d’une table d’une base de données SQL Azure, ainsi qu’ajouter de nouveaux clients. Il s’agit d’une application web anonyme qui permet à quiconque d’afficher ou d’ajouter des clients. La solution Visual Studio pour le complément auto-hébergé et les projets associés peut être téléchargée à partir du référentiel public suivant : Autohosted-Migration-Code-Samples.
La conversion d’un complément SharePoint auto-hébergé en un complément hébergé par un fournisseur comporte plusieurs étapes. Chacune d’entre elles est décrite dans les sections suivantes :
Déploiement de la base de données SQL Azure
Création du site web Azure pour héberger l’application web distante
Enregistrer le complément auprès de votre site SharePoint
Mise à jour et déploiement du site web Azure pour l’application web distante
Reconfiguration du projet Complément SharePoint
Déploiement de la base de données SQL Azure
La première étape de la conversion d’un complément auto-hébergé en un complément hébergé par un fournisseur consiste à déployer la base de données Azure SQL sur laquelle l’application web ASP.NET repose. Il existe plusieurs façons de créer une base de données SQL Azure, dont certaines sont présentées sur le site de documentation Azure : Migration de base de données SQL Server vers SQL Database dans le cloud.
L'approche décrite dans les étapes suivantes utilise le modèle de déploiement de l'application de la couche Données, car c'est ainsi que la base de données est déployée dans un complément SharePoint auto-hébergé. Ceci implique la génération d'un package d'application de la couche Données (*.dacpac) et son utilisation pour créer la base de données.
Création de la base de données SQL Azure
Ouvrez la solution auto-hébergée dans Visual Studio.
Cliquez sur le projet de base de données CustomerDb, puis sélectionnez Build. Cette action génère le fichier CustomerDb.dacpac dans le dossier
[..]\bin\[debug | release].Créez une nouvelle base de données SQL Azure. Connectez-vous au portail Azure et, une fois le tableau de bord chargé, sélectionnez le lien BASES DE DONNÉES SQL dans la marge.
Sélectionnez le lien SERVEURS dans la barre de navigation supérieure, puis sélectionnez le bouton AJOUTER dans le pied de page, comme indiqué dans la figure suivante :
Dans la boîte de dialogue CRÉER UN SERVEUR qui s’affiche, sélectionnez l’ABONNEMENT Azure, le NOM DE CONNEXION et le MOT DE PASSE pour l’utilisateur qui disposera de droits d’accès au serveur et sélectionnez la même RÉGION que celle utilisée lors de la création du site web Azure effectuée précédemment. Notez le nom d’utilisateur et le mot de passe car ceux-ci seront nécessaires au cours d’une prochaine étape.
Une fois le formulaire rempli, sélectionnez l’icône de coche dans l’angle inférieur droit pour créer la base de données. Bien que le serveur soit désormais créé, les uniques ressources qui peuvent y accéder sont les autres services Azure. Notez le nom de la base de données SQL Azure, car vous en aurez besoin au cours d’une étape ultérieure.
Déploiement de la base de données SQL Azure
Pour vous connecter à Azure SQL Database et déployer la base de données, vous devez créer une règle de pare-feu qui autorise le trafic à partir de l’ordinateur qui déploie la base de données. En effet, dans le cas contraire, les connexions à la base de données SQL Azure seront refusées avec des erreurs semblables à celle présentée dans l’illustration suivante.
Pour créer une règle de pare-feu, dans le portail de gestion Azure, sélectionnez la base de données SQL Azure précédemment créée, puis le lien CONFIGURER dans le volet de navigation supérieur.
Dans la section Adresses IP autorisées, votre adresse IP s’affiche sous la même forme que dans l’illustration suivante. Sélectionnez AJOUTER AUX ADRESSES IP AUTORISÉES pour ajouter une règle de pare-feu. Cette opération autorise les connexions à la base de données SQL Azure et le déploiement de la base de données. Sélectionnez Enregistrer dans le pied de page.
Déploiement de la base de données à partir de Visual Studio à l’aide du SDK Azure pour .NET 2.3.
Dans Visual Studio, ouvrez la fenêtre de l’outil Explorateur d’objets SQL Server, cliquez avec le bouton droit de la souris sur le nœud SQL Server, puis sélectionnez Ajouter SQL Server.
Dans la boîte de dialogue Se connecter au serveur, entrez le nom du serveur, définissez l’authentification sur Authentification SQL Server, puis entrez les mêmes nom de connexion et mot de passe que ceux définis lors de la création de la base de données SQL Azure. Le nom du serveur doit être le nom complet du serveur, c’est-à-dire
[server-name].database.windows.net, comme illustré dans la figure suivante.
Une fois connecté à la base de données SQL Azure, développez le nœud du serveur nouvellement ajouté, cliquez avec le bouton droit sur le nœud Bases de données et sélectionnez Publier l’application de la couche Données pour faire apparaître l’Assistant de publication.
Dans la section Application de la couche Données source (.dacpac), utilisez le bouton Parcourir pour trouver le fichier *.dacpac généré lors de la création du projet de base de données au cours d’une précédente étape. Assurez-vous que le nom de la base de données est défini sur CustomerDb.
Sélectionnez Publier pour publier CustomerDb dans la base de données SQL Azure.
Actualisez la fenêtre d'outils Explorateur d'objets SQL Server dans Visual Studio pour voir la base de données CustomerDb listée sous le nœud Bases de données.
Remarque
En fonction de la manière dont la base de données a été créée pour le complément auto-hébergé, un travail supplémentaire peut être requis pour la déployer sur Azure. Pour plus d’informations, consultez Création et gestion de bases de données et d’applications de la couche Données dans Visual StudioCréation et gestion d’applications de la couche Données
Actions à effectuer après le déploiement
Une fois que la base de données SQL Azure a été créée, effectuez une copie de la chaîne de connexion utilisée pour établir une connexion à la base de données. Celle-ci peut être obtenue de deux façons.
Une méthode consiste à se connecter au portail Azure, puis à accéder à la base de données SQL Azure créée au cours de la dernière étape : CustomerDb. Sur la page TABLEAU DE BORD de la base de données, sélectionnez le lien Afficher les chaînes de connexion pour afficher la liste des chaînes de connexion. Effectuer une copie de la chaîne de connexion ADO.NET en vue d’une utilisation ultérieure.
La seconde méthode consiste à obtenir la chaîne de connexion à partir de Visual Studio, à condition que Azure SDK v2.3 soit installé. Dans la fenêtre Explorateur d’objets SQL Server de Visual Studio, sélectionnez la base de données CustomerDb. Une fois la base de données sélectionnée, observez la fenêtre de l’outil Propriétés pour y trouver la chaîne de connexion. Il s’agit de la valeur trouvée dans le portail Azure.
Créer un Site web Azure
L’étape suivante consiste à créer un nouveau site Web Azure où l’application web à distance résidera pour le complément hébergé par le fournisseur. Il faut accomplir cette action en premier, car l’URL de l’application web à distance est nécessaire pour inscrire le complément. Toutefois, l’inscription du complément dans SharePoint doit précéder le déploiement des fichiers pour l’application web ASP.NET, car il existe deux sorties pour le processus d’inscription (ID Client et clé secrète Client) qui sont nécessaires avant le déploiement des fichiers d’application web ASP.NET.
Création d’un nouveau site web Azure
Connectez-vous au Portail Azure. Lorsque le tableau de bord est chargé, cliquez sur le lien de navigation sites web dans la marge de gauche, puis sélectionnez le bouton NOUVEAU dans le pied de page, comme illustré dans la figure ci-dessous.
Dans l’Assistant Nouveau site web, sélectionnez CALCULER, site web et CRÉATION RAPIDE, puis spécifiez une URL et un PLAN D’HÉBERGEMENT WEB. Enfin indiquez la RÉGION dans laquelle le site web doit être créé. Veillez à mémoriser la région sélectionnée, car la même région doit être utilisée pour la base de données SQL Azure créée ultérieurement.
S’il n’existe pas de plan d’hébergement web ou s’il en faut un autre, sélectionnez l’option Créer un plan d’hébergement web. La figure suivante montre un exemple.
Après avoir créé le site web Azure, notez l’URL utilisée pour le site. Dans les figures précédentes, le site créé est
http://spahapptoph.azurewebsites.net.
Enregistrer un nouveau complément
Tous les compléments SharePoint créés à l’aide du modèle de complément doivent être enregistrés auprès de la batterie de serveurs ou du client SharePoint d’hébergement afin d’établir une relation de confiance entre SharePoint et l’application web distante. Ceci implique l’enregistrement d’un nouveau principal de complément auprès de SharePoint, en spécifiant les valeurs suivantes :
- ID client : ID du complément
- Clé secrète client : mot de passe du complément
- Titre : nom du complément
- Domaine de complément : domaine de niveau supérieur de l’application web distante
Lorsqu’un complément auto-hébergé est installé dans SharePoint Online, Office 365 crée automatiquement le principal de complément. L’URL de l’application web à distance est connue, car le site est créé automatiquement. Office 365 prend l’ID client et la clé secrète client et les ajoute au fichier web.config de l’application web à distance. C’est dans web.config qu’une classe fournie par Microsoft (dans le fichier TokenHelper.cs ou .vb) les recherche lors de la validation des requêtes et de l’authentification auprès de SharePoint.
Cependant, dans un complément hébergé par un fournisseur, le développeur doit enregistrer manuellement le complément et mettre à jour manuellement le fichier web.config dans le projet web ASP.NET.
Enregistrement d’un nouveau complément
Accédez à la page d’inscription des compléments du site web SharePoint dans lequel le complément doit être installé. Cette page est accessible à l’adresse
http://[SharePoint-site-url]/_layouts/15/appregnew.aspx.Dans la page d’enregistrement des compléments, définissez le Type de complément sur un complément exécuté sur un serveur web, puis sélectionnez les deux boutons Générer pour créer un ID client et une clé secrète Client.
Entrez le nom du complément dans le champ Titre, puis entrez l’URL du site web Azure cible créé à l’étape précédente dans le champ Domaine de complément. Pour terminer, sélectionnez le bouton Créer.
Une fois le complément enregistré, SharePoint affiche un résumé des informations utilisées dans le formulaire pour créer l’enregistrement. Il est très important de copier ces informations et de les conserver en sécurité, en particulier les valeurs ID client et clé secrète client, car elles seront nécessaires au cours d’une étape ultérieure.
Mise à jour et déploiement du site web Azure pour l’application web distante
L’étape suivante consiste à reconfigurer l’application web à distance de manière à pouvoir la déployer en tant que complément hébergé par un fournisseur, et plus en tant que complément auto-hébergé. Plusieurs méthodes permettent de déployer un site ASP.NET sur un site web Azure, notamment un déploiement direct à partir de Visual Studio, automatiquement à partir d’un contrôle source tel que Visual Studio Team Services, à partir de GitHub, ou même au moyen de l’option FTP, maintes fois éprouvée. Dans cet article, on utilise Visual Studio. Toutefois, avant que l’application web ne puisse être déployée, elle nécessite quelques mises à jour préalables pour fonctionner avec le complément hébergé par un fournisseur.
Pour mettre à jour le projet d’application web distante
La modification la plus importante à apporter à l’application web MVC ASP.NET s’effectue dans le fichier web.config. Ce fichier contient trois paramètres dans le <nœud appSettings> . Il s'agit de ClientId, ClientSecret et SqlAzureConnectionString. Les deux premiers sont utilisés par la classe fournie par Microsoft, dans le fichier TokenHelper.cs ou .vb, pour faciliter l'authentification et la communication avec SharePoint à partir de l'application web distante. Ce dernier, SqlAzureConnectionString, est utilisé par le complément pour se connecter à la base de données Azure SQL.
Dans un complément SharePoint auto-hébergé, Office 365 renseigne les valeurs de ces paramètres lors de la création du site web Azure et de la base de données SQL Azure, à l’installation du complément. Toutefois, dans un complément hébergé par un fournisseur, ceux-ci doivent être définis manuellement avant que le complément ne soit déployé.
Une solution consiste à coller les valeurs définies lors des étapes précédentes de cet article pour les trois paramètres, mais l’inconvénient de cette approche est que, si jamais ces paramètres ont besoin d’être modifiés, le fichier web.config devra être mis à jour et redéployé manuellement sur le site web Azure.
Une autre solution consiste tout simplement à effacer ces paramètres (sans toucher aux clés des paramètres, en définissant juste l’attribut value="" sur une chaîne vide) et à les définir à la place dans les paramètres du site web Azure via le portail Azure. Cette approche signifie que les paramètres peuvent être modifiés sans mettre à jour la base de code. Pour ce faire, procédez comme suit :
Connectez-vous au portail Azure et accédez au site Web Azure créé dans les étapes précédentes.
Dans la page du tableau de bord du site web Azure, sélectionnez CONFIGURER dans le menu de navigation supérieure, puis faites défiler vers le bas jusqu’à la SECTION paramètres des compléments.
Ajoutez trois nouveaux paramètres de complément en utilisant les mêmes noms de paramètre que dans le fichier web.config. Utilisez les valeurs obtenues aux étapes précédentes pour ClientId, ClientSecret, et SqlAzureConnectionString.
Assurez-vous que la chaîne de connexion à la base de données SQL Azure est correcte et valide, car lorsque la chaîne de connexion est affichée via le portail Azure et Visual Studio, l’attribut de mot de passe est remplacé par un masque. Le mot de passe masqué de la chaîne de connexion doit être modifié pour que le mot de passe correct défini lors de la création de la connexion à la base de données SQL Azure soit utilisé.
Déploiement de l’application web distante sur le site web Azure
Les fichiers de l’application web MVC ASP.NET doivent ensuite être déployés sur le site web Azure en tant qu’application web à distance.
Dans Visual Studio, cliquez avec le bouton droit de la souris sur le projet web, puis sélectionnez Publier. La boîte de dialogue de l’Assistant publication web s’ouvre.
Dans cette boîte de dialogue, sélectionnez Sites web Windows Azure, puis sélectionnez Publier.
Sélectionnez le nom du site web Azure qui a été créé à l’étape précédente, comme indiqué dans la figure suivante, puis sélectionnez OK et veillez à ce que l’URL du site commence par HTTPS.
Sélectionnez Valider la connexion pour vous assurer du bon fonctionnement des paramètres et de la connexion.
Sélectionnez Publier pour déclencher le déploiement par Visual Studio de l’application web ASP.NET dans le site web Azure.
Copiez l’URL du site.
Après avoir déployé le site web, Visual Studio lance le navigateur de débogage par défaut et accède au site web Azure. Toutefois, le site affiche une erreur. Elle est due au fait que les contrôleurs MVC ASP.NET disposent d’un attribut (plus précisément l’attribut SharePointContextFilter) qui s’attend à ce que SharePoint envoie certaines valeurs au contrôleur dans l’en-tête d’une requête HTTP POST. Cependant, le navigateur a lancé par défaut une requête HTTP GET ; cette erreur est donc attendue.
Remarque
Pour plus d’options de déploiement des applications web ASP.NET vers un site web Azure, reportez-vous à la rubrique Déploiement Git local vers Azure App Service.
Certificats SSL et domaines personnalisés pour des sites web Azure
Tous les sites web Azure utilisent la convention d’affectation de noms suivante : http[s]://[site-name].azurewebsites.net. Microsoft a déjà ajouté un certificat SSL avec caractères génériques à tous les sites web sous le domaine *.azurewebsites.net, mais les clients sont libres d’associer un domaine personnalisé à leur site web Azure, ainsi que d’utiliser leurs propres certificats SSL pour ces domaines personnalisés.
Pour plus d’informations sur l’utilisation des domaines personnalisés, reportez-vous à la rubrique Mapper un nom DNS personnalisé existant à des applications web Azure.
Pour plus d’informations sur l’ajout d’un certificat SSL personnalisé pour votre nom de domaine personnalisé, reportez-vous à la rubrique Lier un certificat SSL existant à des applications web Azure.
Reconfiguration du projet Complément SharePoint
La dernière étape consiste à reconfigurer le projet Complément SharePoint. Dans le projet Visual Studio pour le complément SharePoint, le type de complément est configuré sur auto-hébergé et doit passer en type hébergé par un fournisseur.
Reconfiguration du projet Complément SharePoint
Ouvrez le fichier AppManifest.xml du projet Complément SharePoint et modifiez l’option Type d’hébergement pour la faire passer de Autohébergement à Hébergement par le fournisseur.
Faites pointer la Page de démarrage du complément sur l’URL de la page de démarrage de l’application web à distance, qui est l’URL du site web Azure. Veillez à inclure la valeur de chaîne de requête {StandardTokens} si elle n’est pas déjà visible. Cela garantit que SharePoint ajoute les jetons de la chaîne de requête principale à l’URL lorsqu’il ouvre l’application web à distance.
Supprimez la référence à l’application web MVC ASP.NET dans le projet Complément SharePoint en sélectionnant le projet Complément SharePoint dans l’Explorateur de solutions de Visual Studio. Dans la fenêtre d’outils Propriétés, définissez la propriété Projet web sur (Aucun), comme illustré dans la figure suivante.
Cette étape nécessite une mise à jour manuelle du fichier AppManifest.xml, car certains paramètres ne sont pas présentés dans le concepteur. Pour ce faire, enregistrez les modifications existantes du fichier AppManifest.xml, puis cliquez avec le bouton droit sur le même fichier dans l’Explorateur de solutions, puis sélectionnez Afficher le code.
Dans le mode code du fichier AppManifest.xml, supprimez les deux références au projet d’application web MVC ASP.NET et au projet d’application de la couche Données SQL, car elles ne sont pas nécessaires dans un complément SharePoint hébergé par un fournisseur.
Créez un nouveau GUID et remplacez le GUID existant dans l’attribut ProductId. Cela indique à SharePoint qu’il s’agit un nouveau complément, et non d’une mise à jour d’un complément existant.
Importante
Si l’attribut ProductId existant est utilisé, SharePoint renvoie l’erreur suivante lors de l’installation du complément converti : « Le complément fourni diffère d’un autre complément doté d’un ID de version et de produit identiques ».
Recherchez l’élément <RemoteWebApplication> et mettez à jour l’attribut ClientId pour qu’il corresponde au GUID obtenu lors de l’inscription du complément auprès de SharePoint et qui a été utilisé dans les paramètres de complément web.config du site web Azure.
Une fois que toutes les modifications du fichier AppManifest.xml ont été enregistrées, le complément est prêt à être testé en tant que complément SharePoint hébergé par un fournisseur. Déployez le complément sur une batterie de serveurs SharePoint ou un site SharePoint Online pour vérifier que les étapes de conversion ont été effectuées correctement.