Erstellen benutzerdefinierter Business Connectivity Services-Connectors mit SharePoint Server 2010

Zusammenfassung:  Erfahren Sie, wie Sie einen benutzerdefinierten Microsoft Business Connectivity Services (BCS)-Connector erstellen, um eine Vielzahl unterschiedlicher Datenquellen in Microsoft SharePoint Server 2010 zu integrieren.

Letzte Änderung: Montag, 22. August 2011

Gilt für: Business Connectivity Services | Office 2010 | Open XML | SharePoint Designer 2010 | SharePoint Foundation 2010 | SharePoint Online | SharePoint Server 2010 | Visual Studio

Inhalt dieses Artikels
Überblick über die Erstellung benutzerdefinierter Business-Konnektivitätsdienste (Business Connectivity Services)-Connectors
Codieren der Assembly
Erstellen des Modells
Verwenden des benutzerdefinierten Connectors
Schlussbemerkung
Weitere Ressourcen

Inhalt

• Überblick über die Erstellung benutzerdefinierter Business-Konnektivitätsdienste (Business Connectivity Services)-Connectors

• Codieren der Assembly

• Erstellen des Modells

• Verwenden des benutzerdefinierten Connectors

• Schlussbemerkung

• Weitere Ressourcen

  Downloadcode: Beispiel für einen benutzerdefinierten BCS-Connector

Überblick über die Erstellung benutzerdefinierter Business-Konnektivitätsdienste (Business Connectivity Services)-Connectors

Microsoft SharePoint Server 2010 ermöglicht die Zusammenarbeit mit externen Systemen (auch Branchensysteme genannt) über Microsoft Business Connectivity Services (BCS). Einige externe Systeme erfordern jedoch flexiblere und mächtigere Mechanismen, um die Daten direkt nutzen zu können. Benutzerdefinierte Business-Konnektivitätsdienste (Business Connectivity Services)-Connectors bieten Ihnen diese Flexibilität und Leistung.

In diesem Artikel werden die Hauptschritte beschrieben, damit Sie einen benutzerdefinierten Business-Konnektivitätsdienste (Business Connectivity Services)-Connector wie folgt erstellen können:

• Codieren der Assembly

• Erstellen des Modells

• Verwenden des benutzerdefinierten Connectors

Das in diesem Artikel verwendete Beispiel erleichtert es Ihnen, einen benutzerdefinierten Connector zu erstellen, der mit dem Dateisystem zusammenarbeitet. Im Grunde erfolgt die Interaktion mit einem angegebenen Ordner über die folgenden Methodentypen:

• Finder  Gibt eine Liste der Dateien zurück, die dem angegebenen Platzhaltersuchkriterium entsprechen.

• SpecificFinder  Gibt Dateiinformationen zu dem angegebenen Dateinamen zurück.

• StreamAccesor  Gibt einen schreibgeschützten Dateidatenstrom für den angegebenen Dateinamen zurück.

Codieren der Assembly

Ein benutzerdefinierter Connector ermöglicht eine tiefgreifende Integration in Business-Konnektivitätsdienste (Business Connectivity Services), da er Mechanismen bereitstellt, mit denen Verbindungen verwaltet, verschiedene Arten von Systemen verwendet, Verbindungen konfiguriert und Metadaten validiert werden können, um sicherzustellen, dass ein gemeinsames Framework verwendet wird. Sie können einen benutzerdefinierten Connector zur Bereitstellung dieser Funktionalität erstellen, indem Sie die folgenden Schnittstellen implementieren:

• ISystemUtility  Erforderlich. Diese Hauptschnittstelle eines Connectors stellt Mechanismen zum Ausführen von Vorgängen an einem externen System bereit.

• IConnectionManager  Optional. Diese Schnittstelle ermöglicht das Öffnen und Schließen von Verbindungen mit dem externen System.

• ITypeReflector  Optional. Diese Schnittstelle ermöglicht die Handhabung von Datenstrukturen des externen Systems.

• ISystemPropertyValidator  Optional. Diese Schnittstelle überprüft die Metadateneigenschaften eines LobSystem-Elements (externes System) und von LobsystemInstance-Elementen (externe Systeminstanzen).

• IAdministrableSystem  Diese Schnittstelle kann implementiert werden, um die Liste der Eigenschaften bereitzustellen, die über die Benutzeroberfläche zur Verwaltung des BDC-Diensts (Business Data Connectivity) konfiguriert werden können.

• ISystemProxyGenerator  Diese Schnittstelle stellt Proxys zusammen, um eine Verbindung mit dem externen System herzustellen; sie können zur Leistungssteigerung gespeichert werden.

Abbildung 1 bietet eine Übersicht über die FileSystemConnector-Klasse.

Abbildung 1. Übersicht über FileSystemConnector

Hinzufügen von Verweisen und Implementieren der Schnittstellen

Um mit der Erstellung eines benutzerdefinierten Connectors beginnen zu können, müssen Sie Verweise auf die folgenden Assemblys hinzufügen:

• Microsoft.BusinessData

• Microsoft.SharePoint

Sie finden die Assemblydateien im Pfad c:\program files\common files\microsoft shared\web server extensions\14\isapi.

Als Nächstes implementieren Sie die folgenden Schnittstellen, damit das Beispiel funktioniert:

• ISystemUtility

• IAdministrableSystem

• ISystemPropertyValidator

In den folgenden Abschnitten werden diese Schnittstellen ausführlicher beschrieben.

ISystemUtility-Schnittstelle

Als Hauptschnittstelle stellt ISystemUtility die Funktionalität zum Ausführen von Vorgängen am externen System bereit.

In unserem Beispiel stellt die ExecuteStatic-Methode die Funktionalität für die Methoden Finder, SpecificFinder und StreamAccesor bereit. Der folgende Code zeigt die Signatur der ExecuteStatic-Methode.

public void ExecuteStatic(IMethodInstance methodInstance, ILobSystemInstance lobSystemInstance, object[] 
methodSignatureArgs, IExecutionContext context)

Sie sollten die In-Parameter und den Basisordner überprüfen, in dem die Vorgänge Create, Read, Update und Delete ausgeführt werden. Dies wird im folgenden Code demonstriert.

if (methodInstance == null)
{
    throw (new ArgumentNullException("methodInstance"));
}
if (lobSystemInstance == null)
{
    throw (new ArgumentNullException("lobSystemInstance"));
}
if (methodSignatureArgs == null)
{
    throw (new ArgumentNullException("args"));
}

object baseFolderValue;
if (!lobSystemInstance.GetProperties().TryGetValue(baseFolderPropertyName, out baseFolderValue))
{
    throw new InvalidOperationException("BaseFolder property is missing");
}

String baseFolderName = baseFolderValue as string;

if (String.IsNullOrEmpty(baseFolderName))
{
    throw new InvalidOperationException("BaseFolder property contains an invalid value.");
}

DirectoryInfo baseFolder = new DirectoryInfo(baseFolderName);

if (!baseFolder.Exists)
{
    throw new InvalidOperationException("Base folder doesn't exist.");
}

Beachten Sie nun Folgendes:

• Der erste Parameter IMethodInstance methodInstance umfasst die MethodInstanceType-Eigenschaft. Damit wird der Methodentyp angegeben, der aufgerufen wird.

• Der dritte Parameter object[] methodSignatureArgs kann viele Unterparameter enthalten, die für die MethodInstanceType-Eigenschaft hilfreich sind.

Mit dieser Information können Sie einen Handler für jeden MethodInstanceType erstellen.

Der Finder-Typ hat folgende Unterparameter:

• methodSignatureArgs[0]: Eine Platzhaltersuchzeichenfolge für den Dateinamen.

• methodSignatureArgs[1]: Das Rückgabeobjekt (eine Liste von FileInfo-Objekten).

Die Unterparameter des Typs Finder sind im folgenden Code dargestellt.

if (methodInstance.MethodInstanceType == MethodInstanceType.Finder)
{
    String wildcard = methodSignatureArgs[0] as string;
    IList<FileInfo> results = new List<FileInfo>();
    methodSignatureArgs[1] = baseFolder.GetFiles(wildcard);
}

Der SpecificFinder-Typ hat folgende Unterparameter:

• methodSignatureArgs[0]: Der Dateiname.

• methodSignatureArgs[1]: Das Rückgabeobjekt (ein FileInfo-Objekt).

Die Unterparameter des Typs SpecificFinder sind im folgenden Code dargestellt.

if (methodInstance.MethodInstanceType == MethodInstanceType.SpecificFinder)
{
    string fileName = methodSignatureArgs[0] as string;
    FileInfo result = new FileInfo(Path.Combine(baseFolder.FullName, fileName));
    if (result.Exists && result.Directory.FullName.Equals(baseFolder.FullName))
    {
        methodSignatureArgs[1] = result;
    }
}

Der StreamAccesor-Typ hat folgende Unterparameter:

• methodSignatureArgs[0]: Der Dateiname.

• methodSignatureArgs[1]: Das Rückgabeobjekt (ein FileStream-Objekt).

Die Unterparameter des Typs StreamAccesor sind im folgenden Code dargestellt.

if (methodInstance.MethodInstanceType == MethodInstanceType.StreamAccessor)
{
    string fileName = methodSignatureArgs[0] as string;
    FileInfo result = new FileInfo(Path.Combine(baseFolder.FullName, fileName));
    if (result.Exists && result.Directory.FullName.Equals(baseFolder.FullName))
    {
        methodSignatureArgs[1] = result.OpenRead();
    }
}

IAdministrableSystem-Schnittstelle

Wie weiter oben in diesem Artikel beschrieben, stellt diese IAdministrableSystem-Schnittstelle eine Liste der Eigenschaften bereit, die über die Verwaltungsoberfläche von Business-Konnektivitätsdienste (Business Connectivity Services) verwaltet werden können. In diesem Fall ist nur eine Eigenschaft namens BaseFolder vorhanden, die das Arbeitsverzeichnis angibt.

Wie in folgendem Code gezeigt, wird über die AdministrableLobSystemInstanceProperties-Eigenschaft der Wert einer Klassenvariablen namens baseFolderPropertyName gespeichert.

public IList<AdministrableProperty> AdministrableLobSystemInstanceProperties
{
    get
    {
        return new List<AdministrableProperty>()
        {
            new AdministrableProperty("Base Folder","The path to the folder that stores the data.", 
              typeof(string), baseFolderPropertyName, typeof(string), true)  
        };
    }
}

ISystemPropertyValidator-Schnittstelle

Mit der ISystemPropertyValidator-Schnittstelle kann die Gültigkeit der Eigenschaften überprüft werden. In diesem Fall ist nur die BaseFolder-Eigenschaft gegeben. Sie überprüfen, ob der Ordner existiert, und lösen eine Ausnahme aus, wenn dies nicht der Fall ist. Dies wird im folgenden Code demonstriert.

public void ValidateLobSystemInstanceProperty(string name, ref object value, string metadataObjectName, 
   Type metadataObjectType)
{
    // Validate whether the given directory exists.
    if (name == baseFolderPropertyName)
    {
        String folderName = value as string;
        if (!Directory.Exists(folderName))
        {
            throw new ArgumentException("The given directory does not exist.");
        }
    }
}

Erstellen des Modells

Sie können das Modell auf dreierlei Weise erstellen: mithilfe von Microsoft SharePoint Designer 2010, mithilfe von Microsoft Visual Studio 2010 oder durch die Erstellung einer Modelldatei, die mit der SharePoint-Zentraladministration importiert werden kann.

Der Einfachheit halber wird in diesem Artikel die dritte Option, die Erstellung einer Modelldatei, untersucht. Als Erstes sollten sich einen Überblick über die FileSystemLOB-Klasse verschaffen, die in Abbildung 2 darstellt ist.

Abbildung 2. Übersicht über FileSystemLOB

In den folgenden Abschnitten werden diese Eigenschaften, Methoden und Bezeichner beschrieben.

FileSystemLOB-Eigenschaften

Das LobSystem-Element verfügt über die SystemUtilityTypeName-Eigenschaft, die durch das folgende XML-Fragment definiert wird. Beachten Sie, dass dies der AdministrableLobSystemProperties-Liste in der IAdministrableSystem-Schnittstelle entspricht.

<Properties>
  <Property Name="SystemUtilityTypeName" Type="System.String">
    BusinessDataConnectivitySamples.Connectors.FileSystemConnector,
    BusinessDataConnectivitySamples.Connectors,
    Version=14.0.0.0,
    Culture=Neutral,
    PublicKeyToken=2154d1c691e2e909
  </Property>
</Properties>

Der vollständig qualifizierte Assemblyname wird in die SystemUtilityTypeName-Eigenschaft eingefügt.

TestFileSystemCustomShimInstance-Instanz

Die TestFileSystemCustomShimInstance-Instanz wird durch das folgende XML-Fragment definiert. Beachten Sie, dass die BaseFolder-Eigenschaft der Eigenschaft in der IAdministrableSystem-Schnittstelle entspricht.

<LobSystemInstance Name="TestFileSystemCustomShim">
  <Properties>
    <Property Name="BaseFolder" Type="System.String">c:\testfolder</Property>
  </Properties>
</LobSystemInstance>

Externe Datei als Inhaltstyp

Das XML-Element Entity bildet den größten Abschnitt des Modells und definiert die Eigenschaften, Methoden und Bezeichner der Dateien. Dies wird im folgenden XML-Fragment dargestellt.

<Entity EstimatedInstanceCount="1000" Name="File" Namespace="BDCSamples.Connectors.FileSystem" Version="1.0.0.0">
<Identifiers>
  <Identifier TypeName="System.String" Name="FileName"/>
</Identifiers>
<Methods>
<Method Name="ReadFile">
<Method Name="ReadFiles">
<Method Name="GetFileContents">
</Methods>
</Entity>

Business-Konnektivitätsdienste (Business Connectivity Services) muss auch über eine Möglichkeit verfügen, jedes Element (in diesem Fall die Datei) eindeutig zu identifizieren. Dies geschieht durch den Bezeichner, der in diesem Beispiel durch die FileName-Eigenschaft gegeben ist.

Als Nächstes folgen die Methoden, die im allgemeinen der folgenden Struktur entsprechen:

• In-Parameter

• Rückgabeparameter

• Methodeninstanzen

• Zugriffssteuerungslisten (ACLs)

Die Methoden werden den Vorgängen zugeordnet, die in der ExecuteInternal-Methode der ISystemUtility-Schnittstelle beschrieben werden. Im folgenden Markup wird nur das XML-Fragment für die ReadFile-Methode dargestellt. Sie können sich die restlichen Vorgänge jedoch in den Dateien ansehen, die zu diesem Artikel gehören (siehe Beispiel für einen benutzerdefinierten BCS-Connector).

<Method Name="ReadFile">
  <Parameters>
  <Parameter Direction="In" Name="FileName">
    <TypeDescriptor TypeName="System.String" IdentifierName="FileName" Name="FileName" />
  </Parameter>
  <Parameter Direction="Return" Name="FileDetails">
    <TypeDescriptor TypeName="System.IO.FileInfo, mscorlib, Version=2.0.0.0, Culture=neutral, 
       PublicKeyToken=b77a5c561934e089" Name="FileDetails">
    <TypeDescriptors>
      <TypeDescriptor Name="Name" TypeName="System.String" IdentifierName="FileName" ReadOnly="true" />
      <TypeDescriptor Name="Attributes" TypeName="System.IO.FileAttributes, mscorlib, Version=2.0.0.0, 
        Culture=neutral, PublicKeyToken=b77a5c561934e089" ReadOnly="true"/>
      <TypeDescriptor Name="LastWriteTimeUtc" TypeName="System.DateTime" ReadOnly="true">
      <Interpretation>
        <NormalizeDateTime LobDateTimeMode="UTC"/>
      </Interpretation>
      </TypeDescriptor>
    </TypeDescriptors>
    </TypeDescriptor>
  </Parameter>
  </Parameters>
  <MethodInstances>
  <MethodInstance Type="SpecificFinder" ReturnParameterName="FileDetails" Name="FileSystemFinder">
    <!--<AccessControlList>
    <AccessControlEntry Principal="Domain\username">
      <Right BdcRight="Execute"/>
    </AccessControlEntry>
    </AccessControlList>-->
  </MethodInstance>
  </MethodInstances>
</Method>

Verwenden des benutzerdefinierten Connectors

Im nächsten Schritt sehen wir uns an, wie der benutzerdefinierte Connector arbeitet. Bevor Sie dies tun können, müssen Sie die folgenden Schritte ausführen:

1. Installieren Sie die Assembly im globalen Assemblycache.

2. Importieren Sie das Modell.

3. Erstellen Sie die externe Liste.

4. Fügen Sie die Dateien in den angegebenen Ordner ein bzw. entfernen Sie sie daraus.

Installieren der Assembly im global Assemblycache

Sie können die Assembly auf verschiedene Weise im globalen Assemblycache installieren, aber für das Beispiel in diesem Artikel ziehen Sie die Assemblydatei einfach in den Ordner c:\windows\assembly.

Importieren des Modells

Als Nächste führen Sie die folgenden Schritte aus, um das Modell von der Zentraladministration zu importieren.

So importieren Sie das Modell von der Zentraladministration

1. Öffnen Sie SharePoint 2010-Zentraladministration.

2. Wählen Sie unter Anwendungsverwaltung den Eintrag Dienstanwendungen verwalten aus.

3. Klicken Sie auf die Dienstanwendung Business Data Connectivity.

4. Klicken Sie auf die Registerkarte Bearbeiten und dann unter Menüband für die Serverkomponente auf Importieren.

5. Wählen Sie die Modelldatei unter BDC-Modelldatei aus (in diesem Beispiel FileSystemConnector.bdcm).

6. Überzeugen Sie sich davon, dass in Dateityp die Option Modell ausgewählt ist.

7. Stellen Sie sicher, dass unter Erweiterte Einstellungen die Optionen Lokalisierte Namen, Eigenschaften und Berechtigungen ausgewählt sind.

8. Klicken Sie auf Importieren.

Das Modell wird daraufhin importiert, wie in Abbildung 3 dargestellt.

Abbildung 3. Importiertes Modell

Klicken Sie auf das Modell, um die externen Inhaltstypen zu erkennen, die in Abbildung 4 zu sehen sind.

Abbildung 4. Externe Inhaltstypen

Erstellen der externen Liste

Die externe Liste kann auf viele verschiedene Weisen erstellt werden. In diesem Artikel wird allerdings nur ein Verfahren beschrieben, das in den folgenden Schritten dargestellt wird.

So erstellen Sie die externe Liste

1. Wechseln Sie zu der Website, auf der Sie die externe Liste erstellen möchten.

2. Klicken Sie im Menü Websiteaktionen auf Alle Websiteinhalte einblenden.

3. Klicken Sie auf Erstellen.

4. Wählen Sie den Typ Externe Liste aus, und klicken Sie dann auf Erstellen.

5. Benennen Sie die Liste, und klicken Sie dann auf Externen Inhaltstyp auswählen.

6. Klicken Sie auf Erstellen.

Die externe Liste kann jetzt Informationen (bzw. Dateien) empfangen, wie in Abbildung 5 dargestellt wird.

Abbildung 5. Erstellte externe Liste

Hinzufügen oder Entfernen von Dateien

Sie fügen Dateien in den Ordner c:\testfolder ein oder löschen Dateien daraus, und die Liste wird entsprechend aktualisiert. Abbildung 6 veranschaulicht diese Listen- und Ordnersynchronisation.

Abbildung 6. Listen- und Ordnersynchronisation

Schlussbemerkung

Mithilfe von Microsoft Business Connectivity Services (BCS) können Sie Verbindungen mit vielen verschiedenen Arten von externen Systemen herstellen. Jede Art von externem System erfordert einen speziellen Connector. Standardmäßig enthält Business-Konnektivitätsdienste (Business Connectivity Services) Connectors für den Zugriff auf Geschäftsdaten, die über Datenbanken und Webdienste verfügbar gemacht werden. Allerdings gibt es Geschäftsdaten, die über andere Mechanismen zur Verfügung gestellt werden oder die zusätzlich aufbereitet werden müssen, bevor Business-Konnektivitätsdienste (Business Connectivity Services) die Daten verwenden kann. Um die einfachen Probleme für ein externes System zu lösen, stellt Business-Konnektivitätsdienste (Business Connectivity Services) auch den Microsoft .NET Framework-Assemblyconnector bereit. Hier sind die Logik zum Herstellen einer Verbindung mit dem externen System und Verarbeitungsfunktionen in einer einfachen Assembly zusammengefasst, die Funktionen verfügbar macht, die von Business-Konnektivitätsdienste (Business Connectivity Services) genutzt werden können. Diese Connectorgruppe deckt zwar die meisten externen Systeme ab, ist aber nicht immer ausreichend. Möglicherweise sind umfassendere Steuerungsmöglichkeiten für Verbindungen und Modelle erforderlich, oder Sie müssen Verbindungen mit vielen externen Systemen desselben Typs herstellen. Diese Probleme werden vom .NET Framework-Assemblyconnector nicht gelöst. Wie in diesem Artikel erläutert, können Sie jedoch einen benutzerdefinierten Connector erstellen, um sie zu lösen.

Weitere Ressourcen

Weitere Informationen finden Sie in den folgenden Ressourcen:

• IAdministrableSystem

• ISystemPropertyValidator

• ISystemUtility

• BDCMetadata-Schema

• Business Connectivity Services (Übersicht) (SharePoint Server 2010)

• BDC-Architektur

• Beispiel-BDC-Modell

• SharePoint Developer Center

• BCS Resource Center | SharePoint 2010