Freigeben über

Verwenden Sie Verbindungszeichenfolgen in XRM-Tools, um eine Verbindung mit Microsoft Dataverse herzustellen.

  • Artikel

Mit Dataverse ermöglicht Ihnen XRM-Tooling die Verbindung mit Ihrer Dataverse-Umgebung über Verbindungszeichenfolgen. Dies ähnelt dem Konzept von Verbindungszeichenfolgen, das in SQL Server verwendet wird. Verbindungszeichenfolgen erhalten native Unterstützung in Konfigurationsdateien inklusive der Möglichkeit der Verschlüsselung der Konfigurationsabschnitte für maximale Sicherheit. Dies ermöglicht es Ihnen, Dataverse-Verbindungen zur Bereitstellungszeit zu konfigurieren und nicht hartcodiert in der Anwendung, um eine Verbindung zu Ihrer Dataverse-Umgebung herzustellen.

Erstellen einer Verbindungszeichenfolge

Sie geben diese Verbindungszeichenfolge in der Datei app.config oder web.config für das Projekt an, wie im folgenden Beispiel angezeigt.

<connectionStrings>  
    <add name="MyCDSServer" connectionString="AuthType=OAuth;Username=jsmith@contoso.onmicrosoft.com;Password=passcode;Url=https://contosotest.crm.dynamics.com;AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;TokenCacheStorePath=c:\MyTokenCache;LoginPrompt=Auto"/>
</connectionStrings>

Wichtig

Wenn Sie vertrauliche Informationen zu app.config oder web.config file hinzufügen, z. B. ein Firmenkennwort, müssen Sie sicherstellen, dass geeignete Sicherheitsvorkehrungen zum Schutz dieser Informationen getroffen werden.

Nachdem Sie die Verbindungszeichenfolge erstellt haben, verwenden Sie diese, um ein CrmServiceClient-Objekt zu erstellen.

//Use the connection string named "MyCDSServer"  
//from the configuration file  
CrmServiceClient svc = new CrmServiceClient(ConnectionString);

Alternativ können Sie auch die ServiceClient-Klasse verwenden.

ServiceClient svc = new ServiceClient(ConnectionString);

Hinweis

Sie müssen die folgende using-Direktive in Ihrem Code verwenden, um auf den System.Configuration-Namespace verweisen, um auf die Verbindungszeichenfolge in Ihrem Code zuzugreifen: using System.Configuration;

Nachdem Sie ein Service-Client-Objekt erstellt haben, können Sie das Objekt verwenden, um in Dataverse Aktionen für Apps auszuführen. Weitere Informationen: Verwenden von XRM-Tooling zur Ausführung von Aktionen in Dataverse

Parameter für Verbindungszeichenfolgen

Die Verbindungszeichenfolge enthält eine Reihe von Name-Wert-Paaren, getrennt durch Semikolons. Die folgende Tabelle enthält unterstützte Parameter, die in beliebiger Reihenfolge eingegeben werden können.

Parametername Beschreibung des Dataflows
ServiceUri, Service Uri, Url oder Server Gibt die URL zur Dataverse-Umgebung an. Die URL kann das http- oder https-Protokoll verwenden, und der Port ist optional. Standardmäßig wird der Port 80 für das http-Protokoll und 443 für das https-Protokoll verwendet. Die Server-URL ist normalerweise im Format https://<organization-name>.crm.dynamics.com

Der Organisationsname muss angegeben werden.
UserName, User Name, UserId oder User Id Gibt die Benutzerkennung an, die den Anmeldeinformationen zugeordnet ist.
Password Gibt das Kennwort für den Benutzernamen, das den Anmeldeinformationen zugeordnet ist.
HomeRealmUri oder Home Realm Uri Gibt den Startbereichs-URL an.
AuthenticationType oder AuthType Gibt den Authentifizierungstyp an, um eine Verbindung mit der Dataverse-Umgebung herzustellen. Gültige Werte sind: AD, IFD (AD FS-aktiviert), OAuth, Certificate, ClientSecret oder Office365. Zulässige Werte für Dataverse-Umgebungen sind jedoch nur OAuth, Certificate, ClientSecret und Office365.

HINWEIS: Der Office365-Authentifizierungstyp ist veraltet und wir empfehlen die Verwendung von OAuth als bevorzugten Authentifizierungstyp. Weitere Informationen: Was sollte ich tun, um meinen Anwendungscode zu reparieren, falls er betroffen ist?
RequireNewInstance Definiert, ob die vorhandene Verbindung wieder verwendet wird, wenn Sie aufgerufen wird, solange die Verbindung noch aktiv ist. Wenn auf true festgelegt, wird das System gezwungen, eine eindeutige Verbindung herzustellen. Wenn Sie dies auf false festlegen, kann die bestehende Verbindung wiederverwendet werden.
ClientId, AppId oder ApplicationId Gibt die ClientID an, die bei der Registrierung Ihrer Anwendung in Microsoft Entra ID oder Active Directory Federation Services (AD FS) zugewiesen wurde.
ClientSecret oder Secret Erforderlich, wenn der Auth-Typ auf ClientSecret festgelegt ist. Zeichenfolge für geheimen Clientschlüssel für die Authentifizierung.
RedirectUri oder ReplyUrl Gibt die Umleitungs-URI der Anwendung an, die Sie in Microsoft Entra ID oder Active Directory Federation Services (AD FS) registriert haben.

Dieser Parameter gilt nur, wenn OAuth als Authentifizierungstyp angegeben ist.
TokenCacheStorePath Gibt den vollständigen Pfad zum Speicherort an, an dem der Benutzertoken gespeichert werden soll. Der laufende Prozess muss über Zugriff auf den angegebenen Pfad verfügen. Es ist die Prozesszuständigkeit, diesen Pfad festzulegen und zu konfigurieren.

Dieser Parameter gilt nur, wenn OAuth als Authentifizierungstyp angegeben ist.
LoginPrompt Gibt an, ob der Benutzer zur Eingabe der Anmeldeinformationen aufgefordert wird, wenn die Anmeldeinformationen nicht angegeben wurden. Gültige Werte sind:

- Always: Fordert immer den Benutzer auf, Anmeldeinformationen anzugeben.
- Auto: Ermöglicht dem Benutzer, in der Anmeldungssteuerelement-Benutzeroberfläche auszuwählen, ob die Eingabeaufforderung angezeigt wird oder nicht.
- Never: Fordert den Benutzer nicht auf, Anmeldeinformationen anzugeben. Wenn für die Verwendung einer Verbindungsmethode keine Benutzeroberfläche bereitgestellt wird, müssen Sie diesen Wert verwenden.

Dieser Parameter gilt nur, wenn OAuth als Authentifizierungstyp angegeben ist.
StoreName oder CertificateStoreName Definiert den Speichernamen, unter dem das Zertifikat für den Fingerabdruck gefunden wird. Wenn festgelegt, ist der Fingerabdruck erforderlich.
Thumbprint oder CertThumbprint Definiert den Fingerabdruck des Zertifikats, der während einer S2S-Verbindung verwendet wird. Wenn festgelegt, ist die AppID erforderlich und die Benutzer-ID und das Kennwort werden ignoriert.
Integrated Security Gibt an, dass aktuelle Windows-Anmeldeinformationen verwendet werden sollen, um zu versuchen, ein Token für die Instanzen zu erstellen. Ab NuGet-Version Microsoft.CrmSdk.XrmTooling.CoreAssembly Version 9.1.0.21

Hinweis

Wenn der AuthType\AuthenticationType OAuth verwendet wird
Für Entwicklungs- und Erstausführungszwecke haben wir die folgenden AppId oder das ClientId bereitgestellt und URI für die Verwendung in OAuth-Flowsn weitergeleitet.
Für die Produktion sollten Sie ein AppId oder ein ClientId erstellen, die spezifisch sind für Ihren Mandanten im Azure Verwaltungsportal.
Beispiel AppId oder ClientId = 51f81489-12ee-4a9e-aaae-a2591f45987d
Beispiel RedirectUri = app://58145B91-0C36-4500-8554-080854F2AC97

Beispiele für Verbindungszeichenfolgen

Die folgenden Beispiele veranschaulichen, wie Sie Verbindungszeichenfolgen für die Verbindung mit Online-Bereitstellungen und Authentifizierungsszenarien verwenden können. Die Beispiele für Verbindungszeichenfolgen für lokale und IFD-Deployment-Instanzen sind nun in der Dokumentation Dynamics 365 Customer Engagement (on-premises) unter: Verwenden Sie Verbindungszeichenfolgen in XRM-Tools, um eine Verbindung herzustellen.

Benanntes Konto mit Office365

Erstellen Sie eine neue Verbindung zu Dataverse mithilfe eines Benutzernamens oder Kennworts über Office365 her.

Hinweis

Diese AuthType ist veraltet und wir empfehlen, OAuth als bevorzugter Authentifizierungstyp zu verwenden. Weitere Informationen: Authentifizieren Sie mithilfe von Office365

<add name="MyCDSServer" 
 connectionString="
  AuthType=Office365;
  Username=jsmith@contoso.onmicrosoft.com; 
  Password=passcode;
  Url=https://contoso.crm.dynamics.com"/>

OAuth unter Verwendung des benannten Kontos in Microsoft 365 mit UX zur Abfrage der Authentifizierungsbestätigung

Erstellen Sie eine neue Verbindung mit Dataverse mit Hilfe einer UserID oder eines Kennworts via OAuth.

Hinweis

OAuth ist der bevorzugte Authentifizierungstyp für die Verbindung zu Dataverse, wenn ein interaktiver Flow verwendet wird. Dieser Authentifizierungstyp bietet volle Unterstützung der Funktionen des bedingten Microsoft Entra ID-Zugriffs und der Multi-Faktor-Authentifizierung.

<add name="MyCDSServer"
 connectionString="
  AuthType=OAuth;
  Username=jsmith@contoso.onmicrosoft.com;
  Password=passcode;
  Url=https://contosotest.crm.dynamics.com;
  AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;
  RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;
  TokenCacheStorePath=c:\MyTokenCache;
  LoginPrompt=Auto"/>

OAuth nutzt gerade angemeldete Benutzers mit mit Zurücksetzen von UX, um auf die Authentifizierung hinzuweisen

Erstellen Sie eine neue Verbindung zu Dataverse unter Verwendung des aktuell angemeldeten Benutzers über OAuth.

Hinweis

OAuth ist der bevorzugte Authentifizierungstyp für die Verbindung zu Dataverse, wenn ein interaktiver Flow verwendet wird. Dieser Authentifizierungstyp bietet volle Unterstützung der Funktionen des bedingten Microsoft Entra ID-Zugriffs und der Multi-Faktor-Authentifizierung.

<add name="MyCDSServer"
 connectionString="
  AuthType=OAuth;
  Username=jsmith@contoso.onmicrosoft.com;
  Integrated Security=true;
  Url=https://contosotest.crm.dynamics.com;
  AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;
  RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;
  TokenCacheStorePath=c:\MyTokenCache\msal_cache.data;
  LoginPrompt=Auto"/>

Zertifikatsbasierte Authentifizierung

Erstellen Sie eine neue Verbindung zu Dataverse mithilfe einer Anwendungs- oder Client-ID und eines Zertifikats.

<add name="MyCDSServer" 
  connectionString="
  AuthType=Certificate;
  url=https://contosotest.crm.dynamics.com;
  thumbprint={CertThumbPrintId};
  ClientId={AppId};"
  />

Auf der ClientId oder dem geheimen Clientschlüssel basierte Authentifizierung

Erstellen Sie eine neue Verbindung zu Dataverse mithilfe einer Anwendungs- oder Client-ID und eines geheimen Clientschlüssels.

<add name="MyCDSServer" 
  connectionString="
  AuthType=ClientSecret;
  url=https://contosotest.crm.dynamics.com;
  ClientId={AppId};
  ClientSecret={ClientSecret}"
  />

Bestimmung Ihres Verbindungsstatus

Um zu bestimmen, ob die Verbindungsaufforderung erfolgreich war, überprüfen Sie den Wert für CrmServiceClient.IsReady. -Eigenschaft verfügbar. Wenn der Wert true ist, ist die Verbindung erfolgreich undSie können mit der Arbeit beginnen. Andernfalls überprüfen Sie die Werte der CrmServiceClient.LastCrmError- und CrmServiceClient.LastCrmException- Eigenschaften, um die Ursache für den Verbindungsfehler festzustellen.

Siehe auch

Erstellen von Windows-Client-Anwendungen mithilfe der XRM-Tools
CrmServiceClient-Konstruktoren verwenden, um eine Verbindung mit Dataverse herzustellen
Verwenden von XRM-Tooling zur Ausführung von Aktionen in Dataverse
CrmServiceClient

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).