Verwenden von Verbindungszeichenfolgen in XRM-Tools

Mit Dynamics 365 Customer Engagement (on-premises) können Sie mit XRM-Tools mithilfe von Verbindungszeichenfolgen eine Verbindung mit Ihrer Instanz herstellen. 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. Auf diese Weise können Sie Dynamics 365 Customer Engagement (on-premises)-Verbindungen zum Zeitpunkt der Bereitstellung konfigurieren und keinen harten Code in Ihrer Anwendung verwenden, um eine Verbindung mit Ihrer Instanz herzustellen.

Hinweis

Die Dokumentation zur Verbindungszeichenfolge, die für Dataverse-Benutzer gilt, ist jetzt in der Power Apps-Dokumentation verfügbar unter: Verwenden von Verbindungszeichenfolgen in XRM-Tools, um eine Verbindung zu Dataverse 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="MyCRMServer" connectionString="AuthType=AD;Url=https://contoso:8080/Test;" />  
</connectionStrings>  

Von Bedeutung

Wenn Sie vertrauliche Informationen zu den Dateien app.config oder web.config hinzufügen, wie beispielsweise ein Kontokennwort, stellen Sie sicher, dass Sie angemessene Sicherheitsvorkehrungen treffen, um die Informationen zu schützen.

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

//Use the pre-configured connection string named "MyCRMServer"
CrmServiceClient crmSvc = new CrmServiceClient(ConfigurationManager.ConnectionStrings["MyCRMServer"].ConnectionString);  

Hinweis

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

Nachdem Sie ein CrmServiceClient Objekt erstellt haben, können Sie das Objekt verwenden, um Aktionen in Dynamics 365 Customer Engagement (on-premises) auszuführen. Weitere Informationen: Verwenden von XRM-Tools zum Ausführen von Aktionen

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
ServiceUri, Service Uri, Url oder Server	Gibt die URL zum Dynamics 365 Server 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 hat in der Regel das Format https://crm-server:port/organization-name für Dynamics 365 Customer Engagement (on-premises). Der Organisationsname muss angegeben werden. Sie können entweder den benutzerfreundlichen oder eindeutigen Namen der Organisation angeben, um eine Verbindung herzustellen. Beispiel: https://contoso/test, https://contoso:5555/test, https://contoso/testoder https://10.10.10.2/test.
Domain	Gibt die Domäne an, in der die Benutzeranmeldeinformationen überprüft 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, der mit Dynamics 365 Customer Engagement (on-premises) verbunden werden soll. Gültige Werte sind: AD, IFD (AD FS aktiviert), OAuthoder Office365. - AD und IFD sind nur für Dynamics 365 Customer Engagement (on-premises)-Instanzen zulässig. - OAuthist für Dynamics 365 Customer Engagement (on-premises) und Dataverse-Instanzen zulässig. Für lokale Versionen ist die Registrierung von ADFS 3.x+ und App\Client-ID bei ADFS für den OAuth Typ erforderlich. - Office365 ist nur für Dataverse-Instanzen zulässig. - Die Verwendung eines Zertifikats oder eines geheimen Clientschlüssels für die Authentifizierung wird in Dataverse unterstützt, jedoch nicht in Dynamics 365 Customer Engagement (on-premises).
RequireNewInstance	Definiert, ob die vorhandene Verbindung wieder verwendet wird, wenn Sie aufgerufen wird, solange die Verbindung noch aktiv ist. Der Standardwert gibt false an, dass die vorhandene Verbindung wiederverwendet werden soll. Wenn auf true festgelegt, wird das System gezwungen, eine eindeutige Verbindung herzustellen.
ClientId, AppId oder ApplicationId	Gibt den ClientID an, der bei der Registrierung Ihrer Anwendung in Azure Active Directory oder Active Directory-Verbunddienste (Active Directory Federation Services, AD FS) zugewiesen wurde.
RedirectUri oder ReplyUrl	Gibt den Umleitungs-URI der Anwendung an, die Sie in Azure Active Directory oder Active Directory-Verbunddiensten (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.
SkipDiscovery	Gibt an, ob die Instanzermittlung aufgerufen werden soll, um den Verbindungs-URI für eine bestimmte Instanz zu bestimmen. Ab der NuGet-Version Microsoft.CrmSdk.XrmTooling.CoreAssembly Version 9.0.2.7 ist der Standardwert = true. Ältere Versionen verwenden falsestandardmäßig . Hinweis: Wenn diese Einstellung auf truefestgelegt ist, ist es wichtig, dass der Benutzer den korrekten und genauen URI für die Zielinstanz angibt.
Thumbprint oder CertificateThumbprint	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.
StoreName oder CertificateStoreName	Definiert den Speichernamen, unter dem das Zertifikat für den Fingerabdruck gefunden wird. Wenn festgelegt, ist der Fingerabdruck erforderlich.

Hinweis

Bei der Verwendung des Authentifizierungstyps OAuth für Entwicklungs- und Prototypingzwecke haben wir die folgende AppId oder ClientId und den Umleitungs-URI für die Verwendung in OAuth-Flows bereitgestellt. Wir verwenden diese in allen unseren Codebeispielen.

Beispiel-AppId oder ClientId = 00001111-aaaa-2222-bbbb-3333cccc4444
Beispiel RedirectUri = app://58145B91-0C36-4500-8554-080854F2AC97

Für die Produktion sollten Sie ein AppId oder ein ClientId erstellen, die spezifisch sind für Ihren Mandanten im Azure Verwaltungsportal.

Beispiele für Verbindungszeichenfolgen

Die folgenden Beispiele zeigen, wie Sie Verbindungszeichenfolgen für die Verbindung mit Dynamics 365 Customer Engagement (on-premises) und IFD-Bereitstellungen verwenden können. Die Beispiele für Verbindungszeichenfolgen für Dataverse-Instanzen sind jetzt in der Power Apps-Dokumentation verfügbar unter: Verwenden von Verbindungszeichenfolgen in XRM-Tools, um eine Verbindung mit Dataverse herzustellen

Integrierte lokale Authentifizierung

<add name="MyCRMServer"
connectionString="AuthType=AD;
Url=https://contoso:8080/Test;" />  

Benanntes Konto mit lokaler Authentifizierung

<add name="MyCRMServer"
connectionString="AuthType=AD;
Url=https://contoso:8080/Test;
Domain=CONTOSO;
Username=jsmith;
Password=passcode" />  

OAuth unter Verwendung des benannten Kontos in Dynamics 365 Customer Engagement (on-premises) mit UX zur Abfrage der Authentifizierungsbestätigung

Erstellen Sie eine neue Verbindung mit einer Benutzer-ID oder einem Passwort über oAuth.

Hinweis

OAuth ist der bevorzugte Authentifizierungstyp für die Verbindung mit Dynamics 365 Customer Engagement (on-premises), wenn ein interaktiver Ablauf verwendet wird. Dieser Authentifizierungstyp unterstützt die Features von Azure Active Directory, bedingtem Zugriff und mehrstufiger Authentifizierung vollständig.

<add name="MyCRMServer"
 connectionString="
  AuthType=OAuth;
  Username=jsmith;
  Password=passcode;
  Url=https://contoso:8080/Test;
  AppId=00001111-aaaa-2222-bbbb-3333cccc4444;
  RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;
  TokenCacheStorePath=c:\MyTokenCache;
  LoginPrompt=Auto"/>  

OAuth nutzt aktuell angemeldete Benutzende mit Fallback-UX für die Aufforderung zur Authentifizierung

Erstellen Sie eine neue Verbindung mit dem aktuell angemeldeten Benutzer über oAuth.

Hinweis

OAuth ist der bevorzugte Authentifizierungstyp für die Verbindung mit Dynamics 365 Customer Engagement (on-premises), wenn ein interaktiver Ablauf verwendet wird. Dieser Authentifizierungstyp unterstützt die Features von Azure Active Directory, bedingtem Zugriff und mehrstufiger Authentifizierung vollständig. Weitere Informationen zu diesem Integrated Security Parameter finden Sie in diesem Thema.

<add name="MyCRMServer"
 connectionString="
  AuthType=OAuth;
  Username=jsmith;
  Integrated Security=true;
  Url=https://contoso:8080/Test;
  AppId=00001111-aaaa-2222-bbbb-3333cccc4444;
  RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;
  TokenCacheStorePath=c:\MyTokenCache;
  LoginPrompt=Auto"/>  

IFD unter Verwendung eines benannten Kontos mit Delegierung an einen Vorbereich

<add name="MyCRMServer"
connectionString="AuthType=IFD;Url=https://contoso:8080/Test;
 HomeRealmUri=https://server-1.server.com/adfs/services/trust/mex/;
Domain=CONTOSO; 
Username=jsmith; 
Password=passcode" />  

Bestimmung Ihres Verbindungsstatus

Um festzustellen, ob die Verbindungsanfrage erfolgreich war, prüfen Sie den Wert der Eigenschaft CrmServiceClient.IsReady. Wenn der Wert true ist, ist die Verbindung erfolgreich undSie können mit der Arbeit beginnen. Andernfalls überprüfen Sie die Werte der Eigenschaften CrmServiceClient.LastCrmError und CrmServiceClient.LastCrmException auf die Ursache für den Verbindungsfehler.

Siehe auch

Erstellen von Windows-Client-Anwendungen mithilfe der XRM-Tools
Verwenden Sie CrmServiceClient-Konstruktoren, um eine Verbindung mit Dynamics 365 Customer Engagement (on-premises) und Dataverse herzustellen
Verwenden von XRM-Tools zum Ausführen von Aktionen
CrmServiceClient