Verbindungszeichenfolgen im XRM-Tooling verwenden

Artikel
07/06/2023

Mit Dynamics 365 Customer Engagement (on-premises) ermöglicht das XRM-Tooling es Ihnen, eine Verbindung zu Ihrer Instanz herzustellen, indem Sie Verbindungszeichenfolgen verwenden. 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 des Bereitstellens konfigurieren und müssen in Ihrer Anwendung keinen Hardcode für die Verbindung zu Ihrer Instanz eingeben.

Notiz

Die Verbindungszeichenfolgedokumentation, die für Benutzer von Dataverse gilt, ist jetzt in der Power Apps Dokumentation verfügbar unter: Verbindungszeichenfolgen in XRM-Tooling zur Verbindung mit Dataverse verwenden

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>

Wichtig

Wenn Sie vertrauliche Informationen zur Datei app.config oder web.config 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 pre-configured connection string named "MyCRMServer"
CrmServiceClient crmSvc = new CrmServiceClient(ConfigurationManager.ConnectionStrings["MyCRMServer"].ConnectionString);

Notiz

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 CrmServiceClient Objekt erstellt haben, können Sie das Objekt werden, um Aktionen in Dynamics 365 Customer Engagement (on-premises) auszuführen. Weitere Informationen: XRM-Tooling zur Ausführung von Aktionen verwenden

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 zu 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 ist normalerweise im Format für https://crm-server:port/organization-name oder für Dynamics 365 Customer Engagement (on-premises) gespeichert. 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/test oder https://10.10.10.2/test.
`Domain`	Gibt die Domäne an, die Anmeldeinformationen von Benutzern überprüft.
`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 die Verbindung zur Dynamics 365 Customer Engagement (on-premises) Instanz herzustellen. Gültige Werte sind: `AD`, `IFD` (AD FS) aktiviert, `OAuth` oder `Office365`. - `AD` und `IFD` sind nur für Dynamics 365 Customer Engagement (on-premises)-Instanzen zulässig. - `OAuth`ist für Dynamics 365 Customer Engagement (on-premises)- und Dataverse-Instanzen zulässig. Für lokale ADFS ist 3.x+ und App\Client-ID-Registrierung mit ADFS für den `OAuth`-Typen erforderlich. - `Office365` ist nur für Dataverse-Instanzen zulässig. – Die Verwendung eines Zertifikats oder eines geheimen Clientschlüssels zur Authentifizierung wird in Dataverse, aber nicht in Dynamics 365 Customer Engagement (on-premises) unterstützt.
`RequireNewInstance`	Definiert, ob die vorhandene Verbindung wieder verwendet wird, wenn Sie aufgerufen wird, solange die Verbindung noch aktiv ist. Standardwert ist `false`, der angibt, dass die bestehende Verbindung wiederverwendet wird. Wenn auf `true` festgelegt, wird das System gezwungen, eine eindeutige Verbindung herzustellen.
`ClientId`, `AppId` or `ApplicationId`	Gibt die `ClientID` an, die bei der Registrierung Ihrer Anwendung in Azure Active Directory oder Active Directory Federation Services (AD FS) zugewiesen wurde.
`RedirectUri` oder `ReplyUrl`	Gibt die Redirect-URI der Anwendung an, die Sie in Azure Active Directory 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 den Benutzer immer auf, Anmeldeinformationen anzugeben. - `Auto`: Erlaubt es dem Benutzer, in der Schnittstelle des Steuerelements für die Anmeldung auszuwählen, ob die Eingabeaufforderung angezeigt werden soll 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 Instanz-Erkennung aufgerufen wird, um die Verbindungs-URI für eine bestimmte Instanz zu bestimmen. Ab NuGet Version Microsoft.CrmSdk.XrmTooling.CoreAssembly 9.0.2.7, Standard = `true`. Standard der ältere Versionen werden `false`. Hinweis: Wenn Sie `true` festlegen, ist es wichtig, dass der Benutzer den entsprechenden und präzisen URI für die Zielinstanz zur Verfügung hat.
`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.

Anmerkung

Wenn Sie den OAuth-Authentifizierungstyp für Entwicklungs- und Erstausführungszwecke verwenden, haben wir die folgende AppId oder ClientId bereitgestellt und Weiterleitungs-URI für die Verwendung in OAuth-Flows weitergeleitet. Wir verwenden diese in allen unseren Codebeispielen.

Beispiel AppId oder ClientId = 51f81489-12ee-4a9e-aaae-a2591f45987d
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 veranschaulichen, wie Sie Verbindungszeichenfolgen für die Verbindung mit Dynamics 365 Customer Engagement (on-premises) und IFD-Bereitstellungen und Authentifizierungsszenarien verwenden können. Die Verbindungszeichenfolgen für Dataverse Instanzen ist jetzt in der Power Apps Dokumentation unter: Verbindungszeichenfolgen in XRM-Tooling zur Verbindung mit Dataverse verfügbar

Integrierte lokale Authentifizierung

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

Benanntes Konto unter Verwendung der lokalen 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 einer neuen Verbindung mithilfe einer Benutzer-ID oder mit einem Kennwort über oAuth.

Notiz

OAuth ist der bevorzuge Authentifizierungstyp für die Verbindung mit Dynamics 365 Customer Engagement (on-premises), wenn ein interaktiver Flow verwendet wird. Dieser Authentifizierungstyp unterstützt die Funktion von Azure Active Directory Bedingter Zugriff und mehrstufige Authentifizierung.

<add name="MyCRMServer"
 connectionString="
  AuthType=OAuth;
  Username=jsmith;
  Password=passcode;
  Url=https://contoso:8080/Test;
  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 einer neuen Verbindung mithilfe dem geraden angemeldeten Benutzer über oAuth.

Notiz

<add name="MyCRMServer"
 connectionString="
  AuthType=OAuth;
  Username=jsmith;
  Integrated Security=true;
  Url=https://contoso:8080/Test;
  AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;
  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
Benutzen Sie CrmServiceClient-Konstruktoren, um sich mit Dynamics 365 Customer Engagement (on-premises) und Dataverse zu verbinden
XRM-Tooling zur Ausführung von Aktionen verwenden
CrmServiceClient

Verbindungszeichenfolgen im XRM-Tooling verwenden

Erstellen einer Verbindungszeichenfolge

Parameter für Verbindungszeichenfolgen

Beispiele für Verbindungszeichenfolgen

Integrierte lokale Authentifizierung

Benanntes Konto unter Verwendung der lokalen Authentifizierung

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

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

IFD unter Verwendung eines benannten Kontos mit Delegierung an einen Vorbereich

Bestimmung Ihres Verbindungsstatus

Siehe auch

Zusätzliche Ressourcen