Explorer la structure du manifeste de l’application et le package d’un complément SharePoint

  • Article

Complément pour la structure d’un package SharePoint

Un package de compléments SharePoint est un fichier doté d’une extension « .app », conforme aux conventions Open Packaging Conventions (OPC). Le package contient les éléments suivants :

  • Fichier manifeste du complément : ce fichier, nommé appmanifest.xml, est obligatoire. Il indique à SharePoint certaines propriétés importantes du complément, notamment son titre et les autorisations à exécuter. Pour en savoir plus sur le contenu de ce fichier, consultez la section Complément pour le fichier manifeste SharePoint de cet article.

  • Packages de solution SharePoint : le complément peut éventuellement inclure un package de solutions SharePoint (fichier .wsp) contenant les composants du site web de complément. Ces composants peuvent être des pages, des instances de liste, des vues, des documents, des fonctionnalités d’étendue web et d’autres composants SharePoint. (Pour plus d’informations sur les composants SharePoint qui peuvent être inclus dans un complément SharePoint, voir Types de composants SharePoint qui peuvent se trouver dans un complément SharePoint.) Le fichier .wsp peut également contenir des compléments Office. Les composants du fichier .wsp sont déployés sur le site web de complément. Pour obtenir un exemple de package de compléments contenant un package de solutions SharePoint, consultez l’article Créer un complément hébergé par un fournisseur comportant un type personnalisé de liste et de contenu SharePoint.

  • Fonctionnalités du site web hôte avec les actions personnalisées ou les composants de complément : en plus des composants SharePoint déployés sur le site web de complément, un complément SharePoint peut également déployer une ou plusieurs actions personnalisées (éléments de menu contextuel ou extensions du ruban) sur le site web hôte. Pour cela, il faut intégrer au package de compléments une fonctionnalité qui ne figure pas dans le fichier .wsp du package, qui déploie les composants destinés au site web hôte. Cette fonctionnalité souple est appelée « fonctionnalité du site web hôte ».

    Les composants de complément sont déployés sur le site web hôte de la même manière. La fonctionnalité web hôte se compose d’un fichier de feature.xml SharePoint standard et d’un ou plusieurs fichiers elements.xml associés. Par exemple, un fichier elements.xml pour une action personnalisée contient un balisage CustomAction pour l’action personnalisée. Il peut également inclure le balisage pour les composants de complément. Seuls ces deux types de composants peuvent se trouver dans la fonctionnalité web hôte. Ces fonctionnalités du site web hôte ne sont pas détaillées dans le manifeste du complément. Cependant, elles représentent des « composants » dans le sens OPC et il existe une relation OPC explicite entre le manifeste du complément et chacun de ces fichiers. Pour obtenir un exemple de package de complément qui inclut une fonctionnalité web hôte, voir Créer des actions personnalisées à déployer avec des compléments SharePoint.

    Remarque

    Les administrateurs clients peuvent installer par lots un complément SharePoint sur plusieurs sites web. Lorsqu’un complément est installé de cette façon, on dit qu’il a une étendue client. Si le complément n’a pas été installé par lots, mais sur chaque site web séparément, il a une étendue web. Si la fonctionnalité du site web hôte comporte les extensions du ruban ou les composants du complément, ils ne sont pas déployés sur les sites web hôtes si le complément est installé par lots. Ainsi, seuls les éléments de menu contextuel sont déployés avec les compléments d’étendue client.

    Ne pas confondre l’étendue de complément avec l’étendue de la fonctionnalité. L’étendue de la fonctionnalité indique où sont déployés les éléments d’une fonctionnalité. Il peut s’agir de la batterie, de l’application web, du site (c’est-à-dire de la collection de sites) et du site web. Seul le site web peut être choisi pour déployer les fonctionnalités des compléments SharePoint (les deux hébergent des fonctionnalités et des fonctionnalités web hôtes à l’intérieur d’un fichier .wsp dans un package de compléments).

    L’étendue de complément désigne l’étendue de l’installation d’un complément. Il peut s’agir du site web (le complément a été installé sur un ou plusieurs sites web, site par site) et du client (le complément a été installé par lots sur tout ou partie des sous-ensembles de sites web de la location d’un client).

    Pour en savoir plus sur les étendues client et web, consultez la rubrique Locations et étendues de déploiement des compléments pour SharePoint.

  • Les fichiers de ressources de localisation (.resx) : ils servent à localiser les aspects d’un manifeste de complément, notamment le titre du complément et les aspects des fonctionnalités du site web hôte dans le package de compléments. (Les composants individuels du package de compléments qui se trouvent dans leur propre package, comme les fichiers .wsp, les packages de sites web Azure et les manifestes de complément, disposent de leur propre processus de localisation. Ce processus est appliqué comme si ces composants ne faisaient pas partie d’un complément SharePoint.) Pour obtenir un exemple de package de compléments contenant des fichiers .resx pour une fonctionnalité du site web hôte, consultez l’article relatif à la localisation des compléments SharePoint.

  • Manifestes de compléments Office : un complément Office peut se trouver dans un ou plusieurs manifestes de compléments Office. Ce composant peut figurer dans le package de compléments uniquement si le complément est chargé vers un catalogue de compléments d’entreprise SharePoint, et non vers l’espace public. Pour en savoir plus, consultez l’article Publier des compléments SharePoint.

Complément pour le fichier manifeste SharePoint

Chaque complément SharePoint inclut un fichier appmanifest.xml. Ce fichier donne à SharePoint les informations nécessaires sur le complément et en définit les propriétés les plus importantes. Voici plusieurs des éléments indiqués dans le manifeste :

  • Le nom interne, l'ID de produit et la version du complément.

  • L’URL de la page d’accueil, c’est-à-dire de la page qui s’affiche au lancement du complément. Cela peut être une page du site web de complément, une page basée sur le cloud ou une page située sur un serveur web ISV.

    Remarque

    Dans certains cas, des restrictions peuvent s’appliquer au type de fichier à spécifier dans l’élément StartPage. Pour en savoir plus, consultez l’article sur l’élément StartPage. Quand vous associez plusieurs paramètres de requête dans la valeur StartPage, vous devez utiliser l’esperluette encodée &, plutôt que & ou un point-virgule pour les ajouter ensemble.

  • D’autres propriétés du complément. Il s’agit du titre et des paramètres régionaux pris en charge par le complément (les deux sont obligatoires), des URL des services traitant les événements avant l’installation, après la mise à niveau et avant la désinstallation, ainsi que du modèle web à utiliser quand le site web de complément est créé.

  • Les demandes d'autorisation dont le complément a besoin pour les ressources SharePoint hors du site web de complément.

  • Une identification, à des fins d’authentification et d’autorisation, du principal de complément. Il s’agit du principal qui reçoit les autorisations. Cela n’est pas obligatoire pour les compléments hébergés sur SharePoint.

  • Une liste des conditions préalables (le cas échéant) à remplir pour pouvoir installer le complément. Par exemple, certaines fonctionnalités doivent être installées et activées, tandis que certains services doivent être concédés sous licence et installés.

Remarque

Le fichier manifeste du complément est le seul élément obligatoire dans le package du complément, mais tous les éléments de la liste précédente ne sont pas des composants obligatoires du fichier.

Pour en savoir plus sur les balises du manifeste du complément, consultez les informations de référence sur le schéma des manifestes des compléments SharePoint. Le contenu de cet article ne remplace pas les informations figurant dans ce nœud, notamment les informations concernant les éléments et les attributs requis. Notez également que le schéma des manifestes de complément SharePoint est différent du schéma des manifestes de complément Office. Vous trouverez des informations sur ce dernier dans les informations de référence sur le schéma des manifestes des compléments Office (v1.1).

L’exemple suivant présente un fichier appmanifest.xml. Dans cet exemple, la page de démarrage du complément est une page ASP.NET située sur un serveur distant, et non une page située sur le site SharePoint. L’URL de la page comprend une chaîne de requête qui transmet l’URL du site web hôte à l’application web distante. Le composant {HostUrl} de la chaîne correspond à un jeton, qui est résolu au lancement du complément. Le complément demande une autorisation d’accès en écriture à toutes les listes du site web hôte. Le principal de complément devant obtenir cette autorisation est l’application web distante.

Utilisez l’élément SupportedLocales ou SupportedLanguages dans votre manifeste de complément. Nous vous recommandons d’utiliser SupportedLocales plutôt que SupportedLanguages. L’élément SupportedLanguages fonctionnera encore même après publication. Toutefois, évitez de l’utiliser. Pour en savoir plus, consultez les articles sur l’élément SupportedLocales et l’élément SupportedLanguages.

Remarque

Même si les valeurs de l’attribut Scope de l’élément AppPermissionRequest ont la même structure qu’une URI, ce sont bien des chaînes littérales. La valeur Scope de l’exemple ne contient aucun espace réservé. Pour en savoir plus sur les autorisations, consultez l’article Autorisations des compléments dans SharePoint.

<?xml version="1.0" encoding="utf-8" ?>
<App xmlns="http://schemas.microsoft.com/sharepoint/2012/app/manifest"
     ProductID="{4a07f3bd-803d-45f2-a710-b9e944c3396e}"
     Version="1.0.0.0"
     SharePointMinVersion="15.0.0.0"
     Name="MySampleApp"
>
  <Properties>
    <Title>My Sample App</Title>
    <StartPage>http://MyRemoteWebApplicationServer/default.aspx/?SPHostUrl={HostUrl}</StartPage>
    <SupportedLocales>
      <SupportedLocale CultureName="en-US" />
    </SupportedLocales>        
  </Properties>

  <AppPermissionRequests>
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web/list" Right="Write"/>
  </AppPermissionRequests>

  <AppPrincipal>
    <RemoteWebApplication ClientId="1ee82b34-7c1b-471b-b27e-ff272accd564" />
  </AppPrincipal>
</App>

Jetons d’URL dans le manifeste de complément

SharePoint fournit plusieurs jetons qui peuvent être utilisés dans l’élément StartPage et d’autres emplacements dans les compléments et les composants des compléments pour représenter des informations qui ne sont pas connues tant que le complément n’est pas exécuté. L’infrastructure SharePoint résout ces jetons. Certains d’entre eux sont utilisés au début de l’URL, alors que d’autres peuvent être utilisés au milieu d’une URL (par exemple, la valeur d’un paramètre de requête). Ces jetons et d’autres peuvent également servir dans différents contextes de développement SharePoint.

Pour en savoir plus sur tous ces jetons et les emplacements où ils peuvent être utilisés, consultez l’article Chaînes URL et jetons dans les compléments pour SharePoint. Pour obtenir des informations plus générales sur les autres jetons et les URL dans SharePoint, consultez l’article URL et jetons dans SharePoint.

Remarque

Ces jetons ne sont pas utilisés dans l’attribut Scope d’un élément AppPermissionRequest.

Voir aussi