MSAL 应用程序中的日志记录Logging in MSAL applications

用于生成日志消息的 Microsoft 身份验证库 (MSAL) 应用,这些消息可以用来诊断问题。Microsoft Authentication Library (MSAL) apps generate log messages that can help diagnose issues. 应用可以通过数行代码配置日志记录,并可对详细程度以及是否记录个人和组织数据进行自定义控制。An app can configure logging with a few lines of code, and have custom control over the level of detail and whether or not personal and organizational data is logged. 建议创建 MSAL 日志记录回调,并提供一种方式来让用户在遇到身份验证问题时提交日志。We recommend you create an MSAL logging callback and provide a way for users to submit logs when they have authentication issues.

日志记录级别Logging levels

MSAL 提供多个日志记录详细级别:MSAL provides several levels of logging detail:

  • 错误:指示出现问题并已生成错误。Error: Indicates something has gone wrong and an error was generated. 用于调试并确定问题。Use for debugging and identifying problems.
  • 警告:不一定会出现错误或故障,只是为了诊断和指出问题。Warning: There hasn't necessarily been an error or failure, but are intended for diagnostics and pinpointing problems.
  • 信息:MSAL 将要记录的事件可为用户提供信息,不一定用于调试。Info: MSAL will log events intended for informational purposes not necessarily intended for debugging.
  • 详细:默认。Verbose: Default. MSAL 将记录库行为的完整详细信息。MSAL logs the full details of library behavior.

个人和组织数据Personal and organizational data

默认情况下,MSAL 记录器不捕获任何高度敏感的个人或组织数据。By default, the MSAL logger doesn't capture any highly sensitive personal or organizational data. 该库提供相关选项,允许你自行决定是否记录个人和组织数据。The library provides the option to enable logging personal and organizational data if you decide to do so.

若要详细了解特定语言的 MSAL 日志记录,请选择与你的语言匹配的选项卡:For details about MSAL logging in a particular language, choose the tab matching your language:

在 MSAL.NET 中进行日志记录Logging in MSAL.NET

备注

有关 MSAL.NET 日志记录的示例和其他信息,请参阅 MSAL.NET WikiSee the MSAL.NET wiki for samples of MSAL.NET logging and more.

在 MSAL 3.x 中,日志记录是在创建应用时使用 .WithLogging 生成器修饰符按应用程序设置的。In MSAL 3.x, logging is set per application at app creation using the .WithLogging builder modifier. 该方法采用以下可选参数:This method takes optional parameters:

  • Level 用于确定你需要哪种级别的日志记录。Level enables you to decide which level of logging you want. 将其设置为“Errors”时,就只会获得错误Setting it to Errors will only get errors
  • PiiLoggingEnabled 在设置为 true 的情况下可以记录个人和组织数据。PiiLoggingEnabled enables you to log personal and organizational data if set to true. 默认情况下,此项设置为 false,不允许应用程序记录个人数据。By default this is set to false, so that your application does not log personal data.
  • LogCallback 设置为一个执行日志记录的委托。LogCallback is set to a delegate that does the logging. 如果 PiiLoggingEnabled 为 true,则此方法会接收消息两次:第一次时 containsPii 参数为 false,消息没有个人数据;第二次时 containsPii 参数为 true,消息可能包含个人数据。If PiiLoggingEnabled is true, this method will receive the messages twice: once with the containsPii parameter equals false and the message without personal data, and a second time with the containsPii parameter equals to true and the message might contain personal data. 在某些情况下(消息不含个人数据),消息是相同的。In some cases (when the message does not contain personal data), the message will be the same.
  • DefaultLoggingEnabled 为平台启用默认日志记录。DefaultLoggingEnabled enables the default logging for the platform. 默认为 false。By default it's false. 如果将它设置为 true,它会在桌面/UWP 应用程序中使用事件跟踪,在 iOS 上使用 NSLog,在 Android 上使用 logcat。If you set it to true it uses Event Tracing in Desktop/UWP applications, NSLog on iOS and logcat on Android.
class Program
 {
  private static void Log(LogLevel level, string message, bool containsPii)
  {
     if (containsPii)
     {
        Console.ForegroundColor = ConsoleColor.Red;
     }
     Console.WriteLine($"{level} {message}");
     Console.ResetColor();
  }

  static void Main(string[] args)
  {
    var scopes = new string[] { "https://microsoftgraph.chinacloudapi.cn/user.read" };

    var application = PublicClientApplicationBuilder.Create("<clientID>")
                      .WithLogging(Log, LogLevel.Info, true)
                      .Build();

    AuthenticationResult result = application.AcquireTokenInteractive(scopes)
                                             .ExecuteAsync().Result;
  }
 }